home *** CD-ROM | disk | FTP | other *** search
/ Die Ultimative Software-P…i Collection 1996 & 1997 / Die Ultimative Software-Pakete CD-ROM fur Atari Collection 1996 & 1997.iso / g / gnu_c / gccdoc.lzh / GCC-ST.TXT < prev   
Encoding:
Text File  |  1994-01-31  |  108.7 KB  |  2,207 lines
  1. How to install and use GCC on your Atari ST or TT
  2.  
  3. Copyright (C) 1991 Frank Ridderbusch
  4.  
  5. Author          : Frank Ridderbusch T35
  6. Created On      : around 1 1/2 years ago
  7. Last Modified By: Frank Ridderbusch
  8. Last Modified On: Wed Sep 23 22:43:30 1992
  9. Update Count    : 88
  10. Status          : Beware, this version is not finished yet.
  11.  
  12. HISTORY 
  13. 31-Jan-1994        Michael White
  14.    Changed format to AtariWriter and text format.
  15. 20-Dec-1991        Frank Ridderbusch T35    
  16.     Last Modified: Fri Dec 20 11:34:04 1991
  17.     Include chapter about C++ compiler driver options
  18. 20-Dec-1991        Frank Ridderbusch T35    
  19.     Last Modified: Fri Dec 20 08:58:56 1991
  20.     Restructuring the utilities chapter. Various minor changes.
  21. 6-Dec-1991        Frank Ridderbusch T35    
  22.     Last Modified: Fri Dec  6 11:21:19 1991
  23.     Run this file through ispell.
  24.  
  25. Introduction
  26. ************
  27.  
  28. This file documents the usage of the GNU C compiler on the Atari ST & TT computers and contains material from other copyrighted 
  29. GNU manuals. The version of the C and C++ compiler, on which this manual is based are mainly 1.40 and 1.40.0 and some facts 
  30. are from GCC 2.x. This manual does not yet cover GCC 2.x in it's complete beauty.
  31.  
  32. Copyright (C) 1988, 1989, 1990 Free Software Foundation, Inc.
  33.           1990, 1991, 1992 Frank Ridderbusch
  34.  
  35. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission 
  36. notice are preserved on all copies.
  37.  
  38. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided 
  39. also that the section entitled "GNU CC General Public License" is included exactly as in the original, and provided that the entire 
  40. resulting derived work is distributed under the terms of a permission notice identical to this one.
  41.  
  42. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for 
  43. modified versions, except that the section entitled ``GNU CC General Public License'' and this permission notice may be included 
  44. in translations approved by the Free Software Foundation instead of in the original English.
  45.  
  46. Copyright 1988, 1989, 1990 Free Software Foundation, Inc.
  47.  
  48. Copyright 1990, 1991, 1992 Frank Ridderbusch
  49.  
  50.  
  51. Introduction
  52.  
  53. This manual documents how to install and run the GNU C compiler on the Atari ST & TT computers. 
  54.  
  55. Beware, this version is not finished yet. GCC 2.x is not yet completly covered, but since the majority of options is equal to GCC 1.x, 
  56. this is not a real problem. Also GAS 1.92 is pending.
  57.  
  58.  
  59. GNU CC GENERAL PUBLIC LICENSE
  60.  
  61.   The license agreements of most software companies keep you at the mercy of those companies.  By contrast, our general public 
  62. license is intended to give everyone the right to share GNU CC.  To make sure that you get the rights we want you to have, we need 
  63. to make restrictionsthat forbid anyone to deny you these rights or to ask you to surrender the rights.  Hence this license agreement.
  64.  
  65. Specifically, we want to make sure that you have the right to give away copies of GNU CC, that you receive source code or else can 
  66. get it if you want it, that you can change GNU CC or use pieces of it in new free programs, and that you know you can do these 
  67. things.
  68.  
  69.   To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights.  For example, if you 
  70. distribute copies of GNU CC, you must give the recipients all the rights that you have.  You must make sure that they, too, receive or 
  71. can get the source code.  And you must tell them their rights.
  72.  
  73.   Also, for our own protection, we must make certain that everyone finds out that there is no warranty for GNU CC.  If GNU CC is 
  74. modified by someone else and passed on, we want its recipients to know that what they have is not what we distributed, so that any 
  75. problems introduced by others will not reflect on our reputation.
  76.  
  77.   Therefore we (Richard Stallman and the Free Software Foundation, Inc.) make the following terms which say what you must do to 
  78. be allowed to distribute or change GNU CC.
  79.  
  80. COPYING POLICIES
  81.  
  82. You may copy and distribute verbatim copies of GNU CC source code as you receive it, in any medium, provided that you 
  83. conspicuously and appropriately publish on each copy a valid copyright notice "Copyright Free Software Foundation, Inc." (or with 
  84. whatever year is appropriate); keep intact the notices on all files that refer to this License Agreement and to the absence of any 
  85. warranty; and give any other recipients of the GNU CC program a copy of this License Agreement along with the program.  You 
  86. may charge a distribution fee for the physical act of transferring a copy.
  87.  
  88. You may modify your copy or copies of GNU CC or any portion of it, and copy and distribute such modifications under the terms of 
  89. Paragraph 1 above, provided that you also do the following:
  90.  
  91. - cause the modified files to carry prominent notices stating that you changed the files and the date of any change; and
  92.  
  93. - cause the whole of any work that you distribute or publish, that in whole or in part contains or is a derivative of GNU CC or any part 
  94. thereof, to be licensed at no charge to all third parties on terms identical to those contained in this License Agreement (except that 
  95. you may choose to grant more extensive warranty protection to some or all third parties, at your option).
  96.  
  97. You may charge a distribution fee for the physical act of transferring a copy, and you may at your option offer warranty protection in 
  98. exchange for a fee.
  99.  
  100. Mere aggregation of another unrelated program with this program (or its derivative) on a volume of a storage or distribution medium 
  101. does not bring the other program under the scope of these terms.
  102.  
  103. You may copy and distribute GNU CC (or a portion or derivative of it, under Paragraph 2) in object code or executable form under 
  104. the terms of Paragraphs 1 and 2 above provided that you also do one of the following:
  105.  
  106. - accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of 
  107. Paragraphs 1 and 2 above; or,
  108.  
  109. - accompany it with a written offer, valid for at least three years, to give any third party free (except for a nominal shipping charge) a 
  110. complete machine-readable copy of the corresponding source code, to be distributed under the terms of Paragraphs 1 and 2 
  111. above; or,
  112.  
  113. - accompany it with the information you received as to where the corresponding source code may be obtained.  (This alternative is 
  114. allowed only for noncommercial distribution and only if you received the program in object code or executable form alone.)
  115.  
  116. For an executable file, complete source code means all the source code for all modules it contains; but, as a special exception, it 
  117. need not include source code for modules which are standard libraries that accompany the operating system on which the 
  118. executable file runs.
  119.  
  120. You may not copy, sublicense, distribute or transfer GNU CC except as expressly provided under this License Agreement.  Any 
  121. attempt otherwise to copy, sublicense, distribute or transfer GNU CC is void and your rights to use the program under this License 
  122. agreement shall be automatically terminated.  However, parties who have received computer software programs from you with this 
  123. License Agreement willnot have their licenses terminated so long as such parties remain in full compliance.
  124.  
  125. If you wish to incorporate parts of GNU CC into other free programs whose distribution conditions are different, write to the Free 
  126. Software Foundation at 675 Mass Ave, Cambridge, MA 02139.  We have not yet worked out a simple rule that can be stated here, 
  127. but we will often permit this.  We will be guided by the two goals of preserving the free status of all derivatives of our free software 
  128. and of promoting the sharing and reuse of software.
  129.  
  130. Your comments and suggestions about our licensing policies and our software are welcome!  Please contact the Free Software 
  131. Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, or call (617) 876-3296.
  132.  
  133. NO WARRANTY
  134.  
  135.   BECAUSE GNU CC IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY NO WARRANTY, TO THE EXTENT 
  136. PERMITTED BY APPLICABLE STATE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING, FREE SOFTWARE FOUNDATION, 
  137. INC, RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GNU CC "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER 
  138. EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 
  139. FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF GNU CC IS WITH 
  140. YOU.  SHOULD GNU CC PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR 
  141. CORRECTION.
  142.  
  143.  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL RICHARD M. STALLMAN, THE FREE SOFTWARE FOUNDATION, 
  144. INC., AND/OR ANY OTHER PARTY WHO MAY MODIFY AND REDISTRIBUTE GNU CC AS PERMITTED ABOVE, BE LIABLE TO YOU 
  145. FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER SPECIAL, INCIDENTAL OR CONSEQUENTIAL 
  146. DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA 
  147. BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE 
  148. WITH ANY OTHER PROGRAMS) GNU CC, EVEN IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR 
  149. FOR ANY CLAIM BY ANY OTHER PARTY.
  150.  
  151.  
  152. Contributors to GNU CC
  153.  
  154.   In addition to Richard Stallman, several people have written parts of GNU CC.
  155.  
  156. - The idea of using RTL and some of the optimization ideas came from the U. of Arizona Portable Optimizer, written by Jack 
  157. Davidson and Christopher Fraser.  See ``Register Allocation and Exhaustive Peephole Optimization'', Software Practice and 
  158. Experience 14 (9), Sept. 1984, 857-866.
  159.  
  160. - Paul Rubin wrote most of the preprocessor.
  161.  
  162. - Leonard Tower wrote parts of the parser, RTL generator, RTL definitions, and of the Vax machine description.
  163.  
  164. - Ted Lemon wrote parts of the RTL reader and printer.
  165.  
  166. - Jim Wilson implemented loop strength reduction and some other loop optimizations.
  167.  
  168. - Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed the support for the SONY NEWS machine.
  169.  
  170. - Charles LaBrec contributed the support for the Integrated Solutions 68020 system.
  171.  
  172. - Michael Tiemann of MCC wrote most of the description of the National Semiconductor 32000 series cpu.  He also wrote the code 
  173. for inline function integration and for the SPARC cpu and Motorola 88000 cpu and part of the Sun FPA support.
  174.  
  175. - Jan Stein of the Chalmers Computer Society provided support for Genix, as well as part of the 32000 machine description.
  176.  
  177. - Randy Smith finished the Sun FPA support.
  178.  
  179. - Robert Brown implemented the support for Encore 32000 systems.
  180.  
  181. - David Kashtan of SRI adapted GNU CC to the Vomit-Making System.
  182.  
  183. - Alex Crain provided changes for the 3b1.
  184.  
  185. - Greg Satz and Chris Hanson assisted in making GNU CC work on HP-UX for the 9000 series 300.
  186.  
  187. - William Schelter did most of the work on the Intel 80386 support.
  188.  
  189. - Christopher Smith did the port for Convex machines.
  190.  
  191. - Paul Petersen wrote the machine description for the Alliant FX/8.
  192.  
  193. Aside from Michael Tiemann, who worked out the front end for GNU C++, and Richard Stallman, who worked out the back end, the 
  194. following people (not including those who have made their contributions to GNU CC) should not go unmentioned.
  195.  
  196. - Doug Lea contributed the GNU C++ library.  This includes support for streams, obstacks, structured files, and other public service 
  197. objects.
  198.  
  199. - Doug Schmidt has spent countless hours pursuing bugs in this compiler for sport.  He also wrote a perfect hash function 
  200. generator in GNU C++ which was used to generate a replacement for the keyword recognizer in the lexical analyzer for both GNU 
  201. CC and GNU C++.
  202.  
  203. - Marc Shapiro and Phillipe Gautron helped me implement features needed for the SOR distributed object management 
  204. environment.
  205.  
  206. - Dirk Grunwald made the collect program usable under COFF.
  207.  
  208. - Angel Li adapted GNU C++ to VMS.
  209.  
  210. - Ron Cole provided additional help getting GNU C++ working on COFF-based systems.
  211.  
  212. - James Clark wrote a name demangler for the GNU C++ naming scheme, and integrated it with the linker.
  213.  
  214. - Michael Powell and Jim Mitchell helped design the GNU C++ exception handling mechanism.
  215.  
  216. The following people contributed specially to the version for the Atari ST & TT.
  217.  
  218. - John R. Dunning did the original port to the Atari ST.
  219.  
  220. - Jwahar R. Bammi improved the port and the libraries.
  221.  
  222. - Eric R. Smith wrote lots of code for the libraries.
  223.  
  224. - David Boyce ported G++ 1.39.1 and the libg++ 1.39.0 to the ST.
  225.  
  226. The following is a not necessarily complete list of people who either contributed code or bugfixes to the libraries: Michal 
  227. Jaegermann, Scott Kolodzieski, Andreas Schwab, Frank Celler, Edgar Roeder, Kai-Uwe Bloem, Allan Pratt, Jens Tingleff, Thomas 
  228. Koenig, Markus Nick. Apologies to those I forgot to mention.
  229.  
  230. Frank Ridderbusch compiled this manual specially for the Atari ST.
  231.  
  232. Introduction
  233.  
  234.   This manual documents how to install and run the GNU C compiler on the Atari ST & TT computers. It does not give an 
  235. introduction in C or M68000 assembler. There is enough material on both subjects available. The user, who is familiar with a C 
  236. compiler, that runs on a U**x system, should have no trouble at all to get GNU C running on the Atari ST. This manual was 
  237. compiled from existing GNU manuals and various bits and pieces from John R. Dunning and Jwahar R. Bammi.
  238.  
  239.   The sections, which describe the compiler driver, the preprocessor and the G++ compiler driver are nearly verbatim copies of 
  240. sections in the respective manuals. The original manuals (Using and Porting GNU CC and The C Preprocessor), were written by 
  241. Richard M. Stallman and Michal D. Tieman (User's Guide to GNU C++). All of these three documents are copyright The Free 
  242. Software Foundation. I modified these sections by removing material, which described features of GNU C for systems like Vaxen or 
  243. Suns. To keep this manual reasonably compact, I extracted only the sections, which describe the supported command options (and 
  244. predefined macros in case of the preprocessor). If the user is interested in the extensions and details, which are implemented in 
  245. GNU C, he has to refer to the original manuals. Whether all described options are useful on the Atari has to be decided.
  246.  
  247.   The facts, which are presented in the assembler and utility sections are mostly derived from the sources of the respective 
  248. programs (from a cross compiler kit by J. R. Bammi based on GNU C 1.31), which were available to me. Other facts were gathered 
  249. by try and error. So, these sections may be a bit shaky.
  250.  
  251.   The first version of this manual was based on GCC 1.37.1. Then, GCC 1.40 and G++ 1.39.1 became available. The most 
  252. noticeable differences were some new options ("-mint", "-G", "-z") and the extended symbol table format. In the beginning of 1992 
  253. the FSF released GCC 2.x. In this release GCC and G++ were merged into one large package. At the time of this writing the current 
  254. version for the Atari is 2.2.2 with patchlevel 2. This manual doesn't cover all new command line options from GCC 2.2.2, but only the 
  255. most valuable (in the authors opinion).  The coverage of GCC 2.x is not yet complete. Also, GAS 1.92 is pending.
  256.  
  257.   Additionally two flavours of libraries are present. One version, which is now mostly maintained by J.R.Bammi, is for the ST running 
  258. the native TOS operating system. The other flavour is maintained by E.R.Smith. This version is specially modified to support MiNT, 
  259. the multitasking TOS extension, also from E.R.Smith. It is the aim of both maintainers to keep the libraries in sync as much as 
  260. possible and possibly merge them together in the future.
  261.  
  262. (Changes are on the way to merge the two library sets into one. Jeff Jackson is currently writing a tsr (terminate and stay resident), 
  263. that provides the UNIXMODE functionality for the extended file sytem at the system trap level aka the kernel. This extended file 
  264. system functionality will then be removed from the library.)
  265.  
  266.   The best place to look for all the components (binaries and sources) is at the moment the Atari archive at terminator. The internet 
  267. address for anonymous ftp is atari.archive.umich.edu (141.211.164.8).  Also a mail server called BART is active. Send a message 
  268. with the word "help" in it to the address atari@atari.archive.umich.edu and BART will explain himself. The maintainers of this archive 
  269. post a monthly message to the USENET newsgroup "comp.sys.atari.st", which explains, how to get things from the archive. The 
  270. packaging of the files may be different as it is explained below.
  271.  
  272.   If you find any errors or typos in this manual or have any other comments, please let me know. My email address is:
  273.  
  274. ridderbusch.pad@sni-usa.com
  275. (Amerika (North & South))
  276. ridderbusch.pad@sni.de
  277. (Rest of world)
  278. Frank_Ridderbusch@pb.maus.de
  279. (MausNet, a FIFO like network in Germany)
  280.  
  281. Installation
  282.  
  283.   There are basically three components, which make up a basic compiling system and which have to be installed. Each component 
  284. is accessed via an environment variable. This three components are:
  285.  
  286. The executables
  287. These are accessed via the normal "PATH" variable, by which all other programs are found and the variable "GCCEXEC".
  288.  
  289. The header files
  290. The preprocessor accesses the header files via the variable "GNUINC". Any C++ header files are accessed via "GXXINC".
  291.  
  292. The libraries
  293. The linker finds the startup file and the required libraries via the variable "GNULIB". The C++ library also belongs into this directory. 
  294.  
  295.   All this stuff basically assumes that you're using a CLI (command line interpreter). A really good choice is "Gulam", which has very 
  296. nice set of features, but there are quite a number of other CLI's around, which also might do the job. If want as much U**x feeling 
  297. as possible, you might consider either "ash", which is compatible to the Bourne shell (ported by Stefan Neuhaus), or E.R.Smiths 
  298. port of "tcsh" or Scott Kolodzieskis port of "BASH 1.12".
  299.  
  300.   Apart from the CLI you definitely should get yourself a "make" utility. Again, good choices here are either the GNU "Make", which 
  301. offers nearly the complete U**x make functionality on the ST or the "PDMAKE", which has only the core make functionality, but has 
  302. on the other hand the advantage, that it requieres fewer system resources.
  303.  
  304.   I suggest the following directory structure on your disk partition:
  305.  
  306. \gnu\bin
  307. for all executable programs. The compiler driver finds the executables in this directory by looking up the environment variable 
  308. "GCCEXEC".
  309.  
  310. \gnu\lib
  311. for the startup object modules and the libraries. The linker find the startup code and the libraries in this directory by looking up the 
  312. variable "GNULIB".
  313.  
  314. \gnu\include
  315. for the header files. The preprocessor finds the include file in this directory by looking up the environment variable "GNUINC".
  316.  
  317.   With earlier versions of GNU CC it was only allowed to put one path into the variables "GNULIB" and "GNUINC". GCC 1.37 and later 
  318. allows you to put several paths into these variables, which are separated by either a "," or a ";". All the mentioned paths are searched 
  319. in order to locate a specific file. However the startup module "crt0.o" is only looked for in the first directory specified in "GNULIB". If 
  320. the preprocessor can't find a include file in one of the directories specified by "GNUINC", it will also search the paths listed in 
  321. "GNULIB".
  322.  
  323.  
  324. Installing the Executables
  325.  
  326.   The compressed archive of the GNU C compiler binary distribution contains the 'common' executables of the GNU compiler. That 
  327. means the compiler driver ("gcc.ttp"), the preprocessor ("gcc-cpp.ttp"), the main body ("gcc-cc1.ttp"), the assembler ("gcc-as.ttp") 
  328. and the linker ("gcc-ld.ttp"), but depending from where you got your GCC the packaging might be different. The just mentioned 
  329. programs are the absolute minimum. To be comfortable, you should get the following support programs:
  330.  
  331. gcc-ar.ttp
  332. is the object library maintainer.
  333.  
  334. gdb.ttp
  335. is the GNU debugger 2.6 modified for the Atari ST. John Dunning did the original port to the Atari. Since then Jwahar Bammi has 
  336. extensively hacked it. GDB now uses DBX debugging information in the object files.  This requires an assembler with version 1.36 or 
  337. greater.
  338.  
  339. sym-ld.ttp
  340. creates the symbol file needed with GDB.
  341.  
  342. gcc-nm.ttp
  343. prints the symbols of a GNU object library or an object file.
  344.  
  345. cnm.ttp
  346. prints the symbol table of a GEMDOS executable.
  347.  
  348. fixstk.ttp
  349. printstk.ttp
  350. are used to modify and print the current stack size of an executable.
  351.  
  352. toglclr.ttp
  353. TOS 1.4 users can toggle the clear above BSS to end of TPA flag for the GEMDOS loader. A newer version of "toglclr.ttp" also 
  354. allows to toggle the loader bits, that were introduced with TOS versions 2.x and 3.x.
  355.  
  356. size68.ttp
  357. This program list the values of the TEXT, DATA, and BSS sections of a ready to run executable.
  358.  
  359. xstrip.ttp
  360. removes the symbol table from an executable.
  361.  
  362.   All this files should go in "\gnu\bin\" directory on your gnu disk. I personally keep my executables in the directory "e:\gnu\bin". You 
  363. should than extend the search path of your CLI to include this directory or you move the compiler driver "gcc.ttp" and the files, 
  364. which are not invoked by "gcc.ttp" ("gcc.ttp" calls "gcc-cpp.ttp", "gcc-cc1.ttp", "gcc-as.ttp" and "gcc-ld.ttp") into the directory, where 
  365. you keep your other executables. The next step is to actually define "GCCEXEC".  "gcc.ttp" uses this variable to locate the
  366. preprocessor, compiler, assembler and the linker.  "GCCEXEC" contains a device/dir/partial-pathname, which not only consists of 
  367. the directory, where the executables are kept, but also a common prefix, which is "gcc-". Assuming you also put the executables in 
  368. the directory as described above, "GCCEXEC" would contain "e:\gnu\bin\gcc-". The value is the same, you would give the compiler 
  369. driver with the "-B" option.
  370.  
  371.   Then you should define a variable called "TEMP". During compilation the output of the various intermediate stages is kept here.  
  372. The variable must not contain a trailing backslash. If you have enough memory, "TEMP" should point to a ramdisk.
  373.  
  374.  
  375. Installing the Libraries
  376.  
  377.   The next thing to do is to install the libraries. The distributed archive contains the following libraries (again, the packaging may 
  378. vary):
  379.  
  380. crt0.o
  381. gcrt0.o
  382. are the startup object modules. The file "gcrt0.o" instead of "crt0.o" is used, if the sources files are compiled for execution profiling 
  383. (the "-pg" option).
  384.  
  385. gnu.olb
  386. gnu16.olb
  387. are the standard libraries, the usual "libc" on other systems.
  388.  
  389. curses.olb
  390. curses16.olb
  391. are ports of the BSD curses.
  392.  
  393. gem.olb
  394. gem16.olb
  395. contain the Atari ST Aes/Vdi/FSM-GDOS bindings.
  396.  
  397. iio.olb
  398. iio16.olb
  399. contain the integer only "printf" and "scanf" functions.
  400.  
  401. pml.olb
  402. pml16.olb
  403. are the portable math libraries.
  404.  
  405. termcap.olb
  406. termcap16.olb
  407. are for the pure "termcap" support.
  408.  
  409. widget.olb
  410. widget16.olb
  411. are a small widget based on "curses"
  412.  
  413.   All these libraries go to a place described by the environment variable "GNULIB". Again this variable must notcontain a trailing 
  414. backslash. Staying with the above example, I've set the variable to "e:\gnu\lib". The libraries, which have a 16 in their names were 
  415. compiled with the "-mshort" option. This makes integers the same size as shorts.
  416.  
  417.   If you like to write programs for MiNT, the TOS multitasking extension from E.R.Smith, you might consider to replace "gnu.olb", 
  418. "gnu16.olb", "iio.olb" and "iio16.olb" with the libraries supplied by Eric Smith. The source and the binaries of these libraries can also 
  419. be retrieved from the Atari archive at terminator. The files are "mntlibxx.zoo for the sources and mntolbxx.zoo for the binaries. They 
  420. are found in the "mint" directory.  xx is the version number, currently 20. Programs written with this libraries will also run under TOS, 
  421. as long no MiNT specific features have been used. (See The C-Compiler Driver, for more info on compiling programs for MiNT (the 
  422. "-mint" option))
  423.  
  424.   Another option is to have both sets of libraries installed. For this you have to rename the MiNT libraries according to the following 
  425. scheme:
  426.  
  427. crt0.o ==> mcrt0.o
  428. gcrt0.o ==> mgcrt0.o
  429. gnu.olb ==> mint.olb
  430. gnu16.olb ==> mint16.olb
  431.  
  432.   To select these files instead of the standard TOS versions and to activate the MiNT specific portions of the header files you have to 
  433. include the "-mint" option in the "gcc.ttp" command line.
  434.  
  435.  
  436. Installing the Header Files
  437.  
  438.   The last bit to install are the header files. They are contained in an archive of their own. The preprocessor now knows about the 
  439. variable "GNUINC". Earlier version had to use the "-I  {prefix}" option, to get to the header files. According to the above examples, 
  440. the files would be put in the directory "e:\gnu\include".  "GNUINC" has to be set accordingly.
  441.  
  442.   If you like to write programs for MiNT, apart from the libraries you also need the MiNT specific include files (also from the Atari 
  443. archive). These are found in the archive "mntincxx.zoo in the "mint" directory.  xx matches the version number of the library. (See 
  444. The C-Compiler Driver for more info on compiling programs for MiNT (the "-mint" option)).
  445.  
  446.   If you choose to have both sets of libraries installed you can keep the TOS specific header files since they are compatible with the 
  447. MiNT ones. 
  448.  
  449.  
  450. Gulam Notes
  451.  
  452.   The programs, which come with the GCC distribution also understand filenames, which use the slash ("/") as a separator. When 
  453. Gulam is your favorite CLI you will stick to the backslashes, since you otherwise lose the feature of command line completition.
  454.  
  455.   If you are using Gulam, you can define "aliases" to reach the executables under more common names.
  456.  
  457. Examples
  458. alias cc e:\gnu\bin\gcc.ttp
  459. alias ar e:\gnu\bin\gcc-ar.ttp
  460. alias as e:\gnu\bin\gcc-as.ttp
  461. alias ld e:\gnu\bin\gcc-ld.ttp
  462.  
  463.   Now you should be able to say "cc foo.c -o foo.ttp and the obvious thing should happen. If you still have trouble, compare your 
  464. settings with the ones from the sample file "gulam.g". That should give you the right idea.
  465.  
  466.   One additional note to Gulam.  "crt0.o" is currently set up to understand the MWC/Atari convention of passing long command lines 
  467. (except it doesn't look into the "_io_vector" part). Gulam users should set "env_style mw", if you want to give long args lines to 
  468. "gcc.ttp".
  469.  
  470.   To summarize the above, here are the settings from my "gulam.g" initialization file. The usage of "UNIXMODE" environment variable 
  471. is explained in the file "unixmode.doc", which is part of the library sources. The "GXXINC" variable is for G++.
  472.  
  473. set env_style mw
  474. setenv TEMP i:
  475. setenv PATH e:\gnu\bin;<your other search paths here>
  476. setenv GCCEXEC e:\gnu\bin\gcc-
  477. setenv GNULIB e:\gnu\lib
  478. setenv GNUINC e:\gnu\include
  479. setenv GXXINC e:\gnu\g++-inc
  480. setenv UNIXMODE 'd/brG'
  481.  
  482.  
  483. Installing G++
  484.  
  485.   For the G++ installation apply the same rules as for the GCC installation. The G++ compiler driver "g++.ttp" and the actual 
  486. compiler "gcc-cc1+.ttp" belong in the same directory as the GCC executables. The preprocessor is shared between G++ and 
  487. GCC. The library "g++.olb" goes into the same directory as all the other libraries. Since G++ has a complete set of include files of 
  488. it's own, they all should be copied into the directory "\gnu\g++-inc". To let the preprocessor know, where it can find the include 
  489. files, the variable "GXXINC" is used.
  490.  
  491.   The above is valid for G++ 1.xx. Since GCC and G++ were merge into one large package with version 2.x, there is no longer a 
  492. special compiler driver for G++.  "gcc.ttp" determines from the file extension, whether the C or C++ compiler should be invoked. 
  493. The file "gcc-cc1plus.ttp" is the actual C++ compiler. This file name is usually truncated to "gcc-cc1p.ttp" in the 8+3 TOS file 
  494. system. What is said about the include files and the variable "GXXINC" is also true for G++ 2.x.
  495.  
  496.   To actually use G++, some requirements have to be fulfilled. You need the GCC include files and libraries with at least patch level 
  497. 72.  Additionally the linker "gcc-ld.ttp" must have at least patch level 22.
  498.  
  499.   The library "g++.olb" is at the moment not 100% 16bit clean. That means, there is at the moment no version, which is compiled 
  500. with the "-mshort" option.
  501.  
  502.  
  503. Memory Requirements
  504.  
  505.   GCC loves memory. A lot. It loves to cons structures. Lots of them. Earlier versions probably won't run at all in less than 1 Meg; the 
  506. version 1.36 of GCC will probably need 2 Meg. The "gcc-cc1.ttp" had 1/2 meg stack, and needs it for compiling large files with 
  507. optimization turned on. Happily, it doesn't need all that stack for smaller files, or even big files without the "-O" option, so it should 
  508. be feasible to make a compiler with a smaller stack (with "fixstk.ttp").
  509.  
  510.   GCC versions 1.37 and later uses another scheme for memory allocation. The programs "gcc-cpp.ttp" and "gcc-cc1.ttp" are setup 
  511. for "_stksize == -1L".  This means, that an executable will use all available memory, doing mallocs from internal heap (as opposed 
  512. to the system heap via "Malloc"), with "SP" initially set at the top, and heap starting just above the "BSS". So if the compiler runs out 
  513. of memory, you probably need more memory (or get rid of accessories, tsr's etc and try).
  514.  
  515.   During my compilation of @TeX 3.1 on my ST, I found that the size of a source file is not main the limiting factor, but the size of a 
  516. function. At that time my ST was equipped with 2.5 megs of memory. About 512 Kb was used for ramdisk, cache and some auto 
  517. folder programs. With this configuration the maximum size of a function, which could be compiled, was about 14-20 KB depending 
  518. on how much code was inlined. Additionally I was able to compile GCC 1.40 and GAS 1.38 on my ST, but for this I had nearly 
  519. disable every program in the auto folder. So, with GCC 1.40 you're doing fine with at least 2.5 megs.
  520.  
  521.   With GCC 2.2 you definitly need more memory. The compiler executable itself is about 850 Kb in size. The C++ compiler is even 
  522. larger (about 1.1 Mb). So, with GCC 2.2 you should have 4 Mb.
  523.  
  524.  
  525. Controlling the C-Compiler Driver ("gcc.ttp")
  526.  
  527.   The GNU C compiler uses a command syntax much like the U**x C compiler. The "gcc.ttp" program accepts options and file 
  528. names as operands.  Multiple single-letter options may not be grouped: "-dr" is very different from "-d -r".
  529.  
  530.   When you invoke GNU CC, it normally does preprocessing, compilation, assembly and linking. File names which end in ".c" are 
  531. taken as C source to be preprocessed and compiled; file names ending in ".i" are taken as preprocessor output to be compiled; 
  532. compiler output files plus any input files with names ending in ".s" are assembled; then the resulting object files, plus any other input 
  533. files, are linked together to produce an executable.
  534.  
  535.   Command options allow you to stop this process at an intermediatestage.
  536.  
  537.   For example, the "-c" option says not to run the linker. Then the output consists of object files output by the assembler.
  538.  
  539.   Other command options are passed on to one stage of processing. Some options control the preprocessor and others the 
  540. compiler itself. Yet other options control the assembler and linker; these are not documented here, but you rarely need to use any of 
  541. them.
  542.  
  543.   Here are the options to control the overall compilation process, including those that say whether to link, whether to assemble, and 
  544. so on.
  545.  
  546. -o {file}
  547. Place output in file {file}. This applies regardless to whatever sort of output is being produced, whether it be an executable file, an 
  548. object file, an assembler file or preprocessed C code.
  549.  
  550. If "-o" is not specified, the default is to put an executable file in "a.out", the object file {source}.c in {source}.o", an assembler file in 
  551. {source}.s, and preprocessed C on standard output.
  552.  
  553. -c
  554. Compile or assemble the source files, but do not link. Produce object files with names made by replacing ".c" or ".s" with ".o" at the 
  555. end of the input file names. Do nothing at all for object files specified as input.
  556.  
  557. -S
  558. Compile into assembler code but do not assemble. The assembler output file name is made by replacing ".c" with ".s" at the end of 
  559. the input file name.  Do nothing at all for assembler source files or object files specified as input.
  560.  
  561. -E
  562. Run only the C preprocessor. Preprocess all the C source files specified and output the results to standard output.
  563.  
  564. -v
  565. Compiler driver program prints the commands it executes as it runs the preprocessor, compiler proper, assembler and linker. Some 
  566. of these are directed to print their own version numbers.
  567.  
  568. -s
  569. The executable is stripped from the DRI compatible or extended symbol table. Certain symbolic debuggers like "sid.prg" work with 
  570. this symbol table. Also the programs "printstk.ttp" and "fixstk.ttp" (See The Utilities for more info) lookup the symbol "_stksize in this 
  571. table.
  572.  
  573. -x
  574. This option directs the linker to discard all local labels while creating the symbol table and write only those labels, which are marked 
  575. global.
  576.  
  577. -G
  578. Instead of the standard DRI compatible symbol table, an extended symbol table is written, which allows symbol names to be up to 
  579. 22 characters long. Most of the utility programs have been updated to work with this format. The most benefit you get with 
  580. "gprof.ttp" and "adb" (the adb-like debugger, originally written for the Sozobon C compiler by Johann Rueg and Don Dugger and 
  581. later improved by Michal Jaegermann (See Debugging for additional info about debugging)).
  582.  
  583. -B {prefix}
  584. The compiler driver program tries {prefix} as a prefix for each program it tries to run. These programs are "gcc-cpp.ttp", 
  585. "gcc-cc1.ttp", "gcc-as.ttp" and "gcc-ld.ttp".
  586.  
  587. For each subprogram to be run, the compiler driver first tries the "-B" prefix, if any. If that name is not found, or if "-B" was not 
  588. specified, the driver tries two standard prefixes, which are "/usr/lib/gcc-" and "/usr/local/lib/gcc-". If neither of those results in a file 
  589. name that is found, the unmodified program name is searched for using the directories specified in your "PATH" environment 
  590. variable.
  591.  
  592. You can get a similar result from the environment variable "GCCEXEC". If it is defined, its value is used as a prefix in the same way. If 
  593. both the "-B" option and the "GCCEXEC" variable are present, the "-B" option is used first and the environment variable value 
  594. second.
  595.  
  596. -z
  597. This option directs all output from "stderr" to the file "compile.err". So, all error messages and warnings, which are printed during a 
  598. compile run are written to this file. The redirection is done by the compiler driver and is therefore only valid for those programs, 
  599. which are subsequently invoked by "gcc.ttp". The "-z" option was introduced only very lately, so not every executable floating 
  600. around might have it.
  601.  
  602.   These options control the details of C compilation itself.
  603.  
  604. -ansi
  605. Support all ANSI standard C programs.
  606.  
  607. This turns off certain features of GNU C that are incompatible with ANSI C, such as the "asm", "inline" and "typeof" keywords, and 
  608. predefined macros such as "unix" and "vax" that identify the type of system you are using. It also enables the undesirable and rarely 
  609. used ANSI trigraph feature.
  610.  
  611. The "-ansi" option does not cause non-ANSI programs to be rejected gratuitously. For that, "-pedantic" is required in addition to 
  612. "-ansi".
  613.  
  614. The macro "__STRICT_ANSI__" is predefined when the "-ansi" option is used.  Some header files may notice this macro and refrain 
  615. from declaring certain functions or defining certain macros that the ANSI standard doesn't call for; this is to avoid interfering with 
  616. any programs that might use these names for other things.
  617.  
  618. -traditional
  619. Attempt to support some aspects of traditional C compilers. Specifically:
  620.  
  621. - All "extern" declarations take effect globally even if they are written inside of a function definition.  This includes implicit 
  622. declarations of functions.
  623.  
  624. - The keywords "typeof", "inline", "signed", "const" and "volatile" are not recognized.
  625.  
  626. - Comparisons between pointers and integers are always allowed.
  627.  
  628. - Integer types "unsigned short" and "unsigned char" promote to "unsigned int".
  629.  
  630. - Out-of-range floating point literals are not an error.
  631.  
  632. - All automatic variables not declared "register" are preserved by "longjmp". Ordinarily, GNU C follows ANSI C: automatic variables 
  633. not declared "volatile" may be clobbered.
  634.  
  635. - In the preprocessor, comments convert to nothing at all, rather than to a space. This allows traditional token concatenation.
  636.  
  637. - In the preprocessor, macro arguments are recognized within string constants in a macro definition (and their values are stringified, 
  638. though without additional quote marks, when they appear in such a context). The preprocessor always considers a string constant 
  639. to end at a newline.
  640.  
  641. - The predefined macro "__STDC__" is not defined when you use "-traditional", but "__GNUC__" is (since the GNU extensions which 
  642. "__GNUC__" indicates are not affected by "-traditional").  If you need to write header files that work differently depending on whether 
  643. "-traditional" is in use, by testing both of these predefined macros you can distinguish four situations: GNU C, traditional GNU C, 
  644. other ANSI C compilers, and other old C compilers.
  645.  
  646. -O
  647. Optimize. Optimizing compilation takes somewhat more time, and a lot more memory for a large function. Without "-O", the 
  648. compiler's goal is to reduce the cost of compilation and to make debugging produce the expected results. Statements are 
  649. independent: if you stop the program with a breakpoint between statements, you can then assign a new value to any variable or 
  650. change the program counter to any other statement in the function and get exactly the results you would expect from the source 
  651. code.
  652.  
  653. Without "-O", only variables declared "register" are allocated in registers. The resulting compiled code is a little worse than produced 
  654. by PCC without "-O".
  655.  
  656. With "-O", the compiler tries to reduce code size and execution time.Some of the "-f" options described below turn specific kinds of 
  657. optimization on or off.
  658.  
  659. -g
  660. Produce debugging information in the operating system's native format (for DBX or SDB). GCC on the Atari produces the DBX 
  661. debugging format. GDB also works with this debugging information.
  662.  
  663. Unlike most other C compilers, GNU CC allows you to use "-g" with "-O". The shortcuts taken by optimized code may occasionally 
  664. produce surprising results: some variables you declared may not exist at all; flow of control may briefly move where you did not 
  665. expect it; some statements may not be executed because they compute constant results or their values were already at hand; some 
  666. statements may execute in different places because they were moved out of loops. Nevertheless it proves possible to debug 
  667. optimized output. This makes it reasonable to use the optimizer for programs that might have bugs.
  668.  
  669. -gg
  670. Produce debugging information in GDB's own format. This option is no longer supported. Do not use it.
  671.  
  672. -w
  673. Inhibit all warning messages.
  674.  
  675. -W
  676. Print extra warning messages for these events:
  677.  
  678. - An automatic variable is used without first being initialized.
  679.  
  680. These warnings are possible only in optimizing compilation, because they require data flow information that is computed only when 
  681. optimizing.  They occur only for variables that are candidates for register allocation.  Therefore, they do not occur for a variable that 
  682. is declared "volatile", or whose address is taken, or whose size is other than 1, 2, 4 or 8 bytes.  Also, they do not occur for 
  683. structures, unions or arrays, even when they are in registers.
  684.  
  685. Note that there may be no warning about a variable that is used only to compute a value that itself is never used, because such 
  686. computations may be deleted by the flow analysis pass before the warnings are printed.
  687.  
  688. These warnings are made optional because GNU CC is not smart enough to see all the reasons why the code might be correct 
  689. despite appearing to have an error.  Here is one example of how this can happen:
  690.  
  691. {
  692.   int x;
  693.   switch (y)
  694.     {
  695.     case 1: x = 1;
  696.       break;
  697.     case 2: x = 4;
  698.       break;
  699.     case 3: x = 5;
  700.     }
  701.   foo (x);
  702. }
  703.  
  704. If the value of "y" is always 1, 2 or 3, then "x" is always initialized, but GNU CC doesn't know this.  Here is another common case:
  705.  
  706. {
  707.   int save_y;
  708.   if (change_y) save_y = y, y = new_y;
  709.  .........
  710.   if (change_y) y = save_y;
  711. }
  712.  
  713. This has no bug because "save_y" is used only if it is set.
  714.  
  715. Some spurious warnings can be avoided if you declare as "volatile" all the functions you use that never return.
  716.  
  717. - A nonvolatile automatic variable might be changed by a call to "longjmp".  These warnings as well are possible only in optimizing 
  718. compilation.
  719.  
  720. - The compiler sees only the calls to "setjmp".  It cannot know where "longjmp" will be called; in fact, a signal handler could call it at 
  721. any point in the code.  As a result, you may get a warning even when there is in fact no problem because "longjmp" cannot in fact 
  722. be called at the place which would cause a problem.
  723.  
  724. - A function can return either with or without a value.  (Falling off the end of the function body is considered returning without a 
  725. value.)  For example, this function would inspire such a warning:
  726.  
  727. foo (a)
  728. {
  729.   if (a > 0)
  730.     return a;
  731. }
  732.  
  733. Spurious warnings can occur because GNU CC does not realize that certain functions (including "abort" and "longjmp") will never 
  734. return.
  735.  
  736. - An expression-statement contains no side effects.
  737.  
  738. In the future, other useful warnings may also be enabled by this option.
  739.  
  740. -Wimplicit
  741. Warn whenever a function is implicitly declared.
  742.  
  743. -Wreturn-type
  744. Warn whenever a function is defined with a return-type that defaults to "int".  Also warn about any "return" statement with no 
  745. return-value in a function whose return-type is not "void".
  746.  
  747. -Wunused
  748. Warn whenever a local variable is unused aside from its declaration, and whenever a function is declared static but never defined.
  749.  
  750. -Wswitch
  751. Warn whenever a "switch" statement has an index of enumeral type and lacks a "case" for one or more of the named codes of that 
  752. enumeration.  (The presence of a "default" label prevents this warning.)   "case" labels outside the enumeration range also provoke 
  753. warnings when this option is used.
  754.  
  755. -Wcomment
  756. Warn whenever a comment-start sequence "/*" appears in a comment.
  757.  
  758. -Wtrigraphs
  759. Warn if any trigraphs are encountered (assuming they are enabled).
  760.  
  761. -Wall
  762. All of the above "-W" options combined.  These are all the options which pertain to usage that we recommend avoiding and that we 
  763. believe is easy to avoid, even in conjunction with macros.
  764.  
  765. The other "-W...." options below are not implied by "-Wall" because certain kinds of useful macros are almost impossible to write 
  766. without causing those warnings.
  767.  
  768. -Wshadow
  769. Warn whenever a local variable shadows another local variable.
  770.  
  771. -Wid-clash-{len}
  772. Warn whenever two distinct identifiers match in the first {len} characters.  This may help you prepare a program that will compile 
  773. with certain obsolete, brain-damaged compilers.
  774.  
  775. -Wpointer-arith
  776. Warn about anything that depends on the "size of" a function type or of "void".  GNU C assigns these types a size of 1, for 
  777. convenience in calculations with "void *" pointers and pointers to functions.
  778.  
  779. -Wcast-qual
  780. Warn whenever a pointer is cast so as to remove a type qualifier from the target type.  For example, warn if a "const char *" is cast to 
  781. an ordinary "char *".
  782.  
  783. -Wwrite-strings
  784. Give string constants the type "const char[{length}]" so that copying the address of one into a "non-const char *" pointer will get a 
  785. warning.  These warnings will help you find at compile time code that can try to write into a string constant, but only if you have 
  786. been very careful about using "const" in declarations and prototypes.  Otherwise, it will just be a nuisance; this is why we did not 
  787. make "-Wall" request these warnings.
  788.  
  789. -p
  790. Generate extra code to write profile information suitable for the analysis program "prof". This is useless on the Atari ST. Use "-pg" 
  791. instead.
  792.  
  793. -pg
  794. Generate extra code to write profile information suitable for the analysis program "gprof".
  795.  
  796. -l{library}
  797. Search a standard list of directories for a library named {library}, which is actually a file named "$GNULIB\{library}.olb". The linker 
  798. uses this file as if it had been specified precisely by name.
  799.  
  800. The directories searched include several standard system directories plus any that you specify with "-L".
  801.  
  802. Normally the files found this way are library files---archive files whose members are object files.  The linker handles an archive file by 
  803. scanning through it for members which define symbols that have so far been referenced but not defined.  But if the file that is found 
  804. is an ordinary object file, it is linked in the usual fashion.  The only difference between using an "-l" option and specifying a file name 
  805. is that "-l" searches several directories.
  806.  
  807. -L{dir}
  808. Add directory {dir} to the list of directories to be searched for {-l}.
  809.  
  810. -nostdlib
  811. Don't use the standard system libraries and startup files when linking. Only the files you specify (plus "gnulib") will be passed to the 
  812. linker.
  813.  
  814. -m{machinespec}
  815. Machine-dependent option specifying something about the type of target machine. These options are defined by the macro 
  816. "TARGET_SWITCHES" in the machine description. The default for the options is also defined by that macro, which enables you to 
  817. change the defaults.
  818.  
  819. These are the "-m" options defined in the 68000 machine description:
  820.  
  821. -m68000
  822. -mc68000
  823. Generate output for a 68000. This is the default on the Atari ST.
  824.  
  825. -m68020
  826. -mc68020
  827. Generate output for a 68020 (rather than a 68000).
  828.  
  829. -m68881
  830. Generate output containing 68881 instructions for floating point.
  831.  
  832. -msoft-float
  833. Generate output containing library calls for floating point.
  834.  
  835. -mshort
  836. Consider type "int" to be 16 bits wide, like "short int" and causes the macro "__MSHORT__" to be defined. Using this option also 
  837. causes the library "{library}16.olb" to be linked. (Also Predefined Macros for more info)
  838.  
  839. -mint
  840. Compile for MiNT (MiNT is not TOS). The macro "__MINT__" is defined and the linker links with the mint library "-lmint"  before linking 
  841. with the normal C library "-lgnu". Also, the linker uses the startup file "mcrt0.o" instead of the normal "crt0.o". If "-mshort" is also 
  842. specified, then both the macros "__MSHORT__"  and "__MINT__" are defined and the linker links with "-lmint16 -lgnu16".
  843.  
  844. -mnobitfield
  845. Do not use the bit-field instructions.  "-m68000 implies "-mnobitfield".
  846.  
  847. -mbitfield
  848. Do use the bit-field instructions.  "-m68020" implies "-mbitfield".  This is the default if you use the unmodified sources.
  849.  
  850. -mrtd
  851. Use a different function-calling convention, in which functions that take a fixed number of arguments return with the "rtd" instruction, 
  852. which pops their arguments while returning. This saves one instruction in the caller since there is no need to pop the arguments 
  853. there.
  854.  
  855. This calling convention is incompatible with the one normally used on U**x, so you cannot use it if you need to call libraries 
  856. compiled with the U**x compiler.
  857.  
  858. Also, you must provide function prototypes for all functions that take variable numbers of arguments (including "printf"); otherwise 
  859. incorrect code will be generated for calls to those functions.
  860.  
  861. In addition, seriously incorrect code will result if you call a function with too many arguments.  (Normally, extra arguments are 
  862. harmlessly ignored.)
  863.  
  864. The "rtd" instruction is supported by the 68010 and 68020 processors, but not by the 68000.
  865.  
  866. -f{flag}
  867. Specify machine-independent flags.  Most flags have both positive and negative forms; the negative form of "-ffoo" would be 
  868. "-fno-foo".  In the table below, only one of the forms is listed---the one which is not the default.  You can figure out the other form by 
  869. either removing "no-" or adding it.
  870.  
  871. -ffloat-store
  872. Do not store floating-point variables in registers.  This prevents undesirable excess precision on machines such as the 68000 where 
  873. the floating registers (of the 68881) keep more precision than a "double" is supposed to have.
  874.  
  875. For most programs, the excess precision does only good, but a few programs rely on the precise definition of IEEE floating point.  
  876. Use "-ffloat-store" for such programs.
  877.  
  878. -fno-asm
  879. Do not recognize "asm", "inline" or "typeof" as a keyword.  These words may then be used as identifiers.
  880.  
  881. -fno-defer-pop
  882. Always pop the arguments to each function call as soon as that function returns.  Normally the compiler (when optimizing) lets 
  883. arguments accumulate on the stack for several function calls and pops them all at once.
  884.  
  885. -fstrength-reduce
  886. Perform the optimizations of loop strength reduction and elimination of iteration variables.
  887.  
  888. -fcombine-regs
  889. Allow the combine pass to combine an instruction that copies one register into another. This might or might not produce better 
  890. code when used in addition to "-O". I am interested in hearing about the difference this makes. (Only GCC and G++ 1.40).
  891.  
  892. -fforce-mem
  893. Force memory operands to be copied into registers before doing arithmetic on them.  This may produce better code by making all 
  894. memory references potential common subexpressions.  When they are not common subexpressions, instruction combination 
  895. should eliminate the separate register-load.  I am interested in hearing about the difference this makes.
  896.  
  897. -fforce-addr
  898. Force memory address constants to be copied into registers before doing arithmetic on them. This may produce better code just as 
  899. "-fforce-mem" may.
  900.  
  901. -fomit-frame-pointer
  902. Don't keep the frame pointer in a register for functions that don't need one.  This avoids the instructions to save, set up and restore 
  903. frame pointers; it also makes an extra register available in many functions.  It also makes debugging impossible.
  904.  
  905. On some machines, such as the Vax, this flag has no effect, because the standard calling sequence automatically handles the 
  906. frame pointer and nothing is saved by pretending it doesn't exist.  The machine-description macro "FRAME_POINTER_REQUIRED" 
  907. controls whether a target machine supports this flag.
  908.  
  909. -finline-functions
  910. Integrate all simple functions into their callers. The compiler heuristically decides which functions are simple enough to be worth 
  911. integrating in this way.
  912.  
  913. If all calls to a given function are integrated, and the function is declared "static", then the function is normally not output as 
  914. assembler code in its own right.
  915.  
  916. -fcaller-saves
  917. Enable values to be allocated in registers that will be clobbered by function calls, by emitting extra instructions to save and restore 
  918. the registers around such calls.  Such allocation is done only when it seems to result in better code than would otherwise be 
  919. produced.
  920.  
  921. This option is enabled by default on certain machines, usually those which have no call-preserved registers to use instead.
  922.  
  923. -fkeep-inline-functions
  924. Even if all calls to a given function are integrated, and the function is declared "static", nevertheless output a separate run-time 
  925. callable version of the function.
  926.  
  927. -fwritable-strings
  928. Store string constants in the writable data segment and don't uniquize them.  This is for compatibility with old programs which 
  929. assume they can write into string constants. Writing into string constants is a very bad idea; "constants" should be constant.
  930.  
  931. -fcond-mismatch
  932. Allow conditional expressions with mismatched types in the second and third arguments. The value of such an expression is void.
  933.  
  934. -fno-function-cse
  935. Do not put function addresses in registers; make each instruction that calls a constant function contain the function's address 
  936. explicitly.
  937.  
  938. This option results in less efficient code, but some strange hacks that alter the assembler output may be confused by the 
  939. optimizations performed when this option is not used.
  940.  
  941. -fvolatile
  942. Consider all memory references through pointers to be volatile.
  943.  
  944. -fshared-data
  945. Requests that the data and non-"const" variables of this compilation be shared data rather than private data.  The distinction makes 
  946. sense only on certain operating systems, where shared data is shared between processes running the same program, while private 
  947. data exists in one copy per process.
  948.  
  949. -funsigned-char
  950. Let the type "char" be the unsigned, like "unsigned char".
  951.  
  952. Each kind of machine has a default for what "char" should be. It is either like "unsigned char" by default or like "signed char" by 
  953. default.  (Actually, at present, the default is always signed.)
  954.  
  955. The type "char" is always a distinct type from either "signed char" or "unsigned char", even though its behavior is always just like one 
  956. of those two.
  957.  
  958. Note that this is equivalent to "-fno-signed-char", which is the negative form of "-fsigned-char".
  959.  
  960. -fsigned-char
  961. Let the type "char" be signed, like "signed char".
  962.  
  963. Note that this is equivalent to "-fno-unsigned-char", which is the negative form of "-funsigned-char".
  964.  
  965. -ffixed-{reg}
  966. Treat the register named {reg} as a fixed register; generated code should never refer to it (except perhaps as a stack pointer, frame 
  967. pointer or in some other fixed role).
  968.  
  969. {reg} must be the name of a register. The register names accepted are machine-specific and are defined in the 
  970. "REGISTER_NAMES" macro in the machine description macro file.
  971.  
  972. This flag does not have a negative form, because it specifies a three-way choice.
  973.  
  974. -fcall-used-{reg}
  975. Treat the register named {reg} as an allocatable register that is clobbered by function calls.  It may be allocated for temporaries or 
  976. variables that do not live across a call. Functions compiled this way will not save and restore the register {reg}.
  977.  
  978. Use of this flag for a register that has a fixed pervasive role in the machine's execution model, such as the stack pointer or frame 
  979. pointer, will produce disastrous results.
  980.  
  981. This flag does not have a negative form, because it specifies a three-way choice.
  982.  
  983. -fcall-saved-{reg}
  984. Treat the register named {reg} as an allocatable register saved by functions. It may be allocated even for temporaries or variables 
  985. that live across a call. Functions compiled this way will save and restore the register{reg} if they use it.
  986.  
  987. Use of this flag for a register that has a fixed pervasive role in the machine's execution model, such as the stack pointer or frame 
  988. pointer, will produce disastrous results.
  989.  
  990. A different sort of disaster will result from the use of this flag for a register in which function values may be returned.
  991.  
  992. This flag does not have a negative form, because it specifies a three-way choice.
  993.  
  994. -pedantic
  995. Issue all the warnings demanded by strict ANSI standard C; reject all programs that use forbidden extensions.
  996.  
  997. Valid ANSI standard C programs should compile properly with or without this option (though a rare few will require "-ansi"). 
  998. However, without this option, certain GNU extensions and traditional C features are supported as well. With this option, they are 
  999. rejected. There is no reason to use this option; it exists only to satisfy pedants.
  1000.  
  1001. These options control the C preprocessor, which is run on each C source file before actual compilation. If you use the "-E" option, 
  1002. nothing is done except C preprocessing. Some of these options make sense only together with "-E" because they request 
  1003. preprocessor output that is not suitable for actual compilation.
  1004.  
  1005. -C
  1006. Tell the preprocessor not to discard comments. Used with the "-E" option.
  1007.  
  1008. -I{dir}
  1009. Search directory {dir} for include files.
  1010.  
  1011. -I-
  1012. Any directories specified with "-I" options before the "-I-" option are searched only for the case of "#include "{file}""; they are not 
  1013. searched for "#include <{file}>".
  1014.  
  1015. If additional directories are specified with "-I" options after the "-I-", these directories are searched for all "#include" directives. 
  1016. (Ordinarily all "-I" directories are used this way.)
  1017.  
  1018. In addition, the "-I-" option inhibits the use of the current directory as the first search directory for "#include "{file}"". Therefore, the 
  1019. current directory is searched only if it is requested explicitly with "-I.". Specifying both "-I-" and "-I." allows you to control precisely 
  1020. which directories are searched before the current one and which are searched after.
  1021.  
  1022. -nostdinc
  1023. Do not search the standard system directories for header files.  Only the directories you have specified with "-I" options (and the 
  1024. current directory, if appropriate) are searched.
  1025.  
  1026. Between "-nostdinc" and "-I-", you can eliminate all directories from the search path except those you specify.
  1027.  
  1028. -M
  1029. Tell the preprocessor to output a rule suitable for "make" describing the dependencies of each source file.  For each source file, the 
  1030. preprocessor outputs one "make"-rule whose target is the object file name for that source file and whose dependencies are all the 
  1031. files "#include"d in it. This rule may be a single line or may be continued with "\"-newline if it is long.
  1032.  
  1033. "-M" implies "-E".
  1034.  
  1035. -MM
  1036. Like "-M" but the output mentions only the user-header filesincluded with "#include "{file}"". System header files included with 
  1037. "#include <@var{file}>" are omitted.
  1038.  
  1039. "-MM" implies "-E".
  1040.  
  1041. -D{macro}
  1042. Define macro {macro} with the empty string as its definition.
  1043.  
  1044. -D{macro}={defn}
  1045. Define macro {macro} as {defn}.
  1046.  
  1047. -U{macro}
  1048. Undefine macro {macro}.
  1049.  
  1050. -T
  1051. Support ANSI C trigraphs. You don't want to know about this brain-damage. The "-ansi" option also has this effect.
  1052.  
  1053.  
  1054. Controlling the C++-Compiler Driver (g++.ttp)
  1055.  
  1056.   The GNU C++ compiler uses a command syntax much like the AT&T C++ compiler. The "g++.ttp" program accepts options and 
  1057. file names as operands.  Multiple single-letter options may not be grouped: "-dr" is very different from "-d -r".
  1058.  
  1059. When you invoke GNU C++, it normally does preprocessing, compilation, assembly and linking.  File names which end in ".c", 
  1060. ".cc", or ".C" are taken as GNU C++ source to be preprocessed and compiled; compiler output files plus any input files with names 
  1061. ending in ".s" are assembled; then the resulting object files, plus any other input files, are linked together to produce an executable.
  1062.  
  1063. Unlike C++, there is no "-F" option.  This is because GNU C++ is a native-code C++ compiler, not a front-end pre-processor.  The 
  1064. advantages of this organization are faster compilation speed, better error-reporting capabilities, better opportunity for compiler 
  1065. optimization, and true source-level debuggability with the GDB debugger (version 3.4 or higher).
  1066.  
  1067. Command options allow you to stop this process at an intermediate stage. For example, the "-c" option says not to run the linker.  
  1068. Then the output consists of object files output by the assembler.
  1069.  
  1070. Other command options are passed on to one stage.  Some options control the preprocessor and others the compiler itself.  Yet 
  1071. other options control the assembler and linker; these are not documented here because the GNU assembler and linker are not yet 
  1072. released.
  1073.  
  1074. Here are the options to control the overall compilation process, including those that say whether to link, whether to assemble, and 
  1075. so on. The options, which don't have any text, behave exactly as their GCC counterparts. 
  1076.  
  1077. With GCC 2.x there is no independend compiler driver for C++.  "gcc.ttp" handles both cases. One major difference between 
  1078. "g++.ttp" from version 1.xx and "gcc.ttp" from version 2.x is, that you have to explicitly link with "g++.olb". Therefore when you 
  1079. compile C++ programs with GCC 2.x you alway have to include "-lg++" on the command line, when you create the final 
  1080. executable.
  1081.  
  1082. -o {file}
  1083.  
  1084. -c
  1085. It is intended that the compiler driver of GNU C++ will invoke the appropriate translator (or series of translators) for a given source 
  1086. file.  Currently, the translators are selected on the basis of their file
  1087. extension.  So that one driver can be used for many different translators, it is important that these extensions be distinct.  It is 
  1088. strongly suggested that users become accustomed to using a ".cc" file extension for GNU C++ code, to distinguish it from the ".c" 
  1089. file extension already used for GNU CC code.
  1090.  
  1091. -S
  1092. -E
  1093. -v
  1094. -s
  1095. -x
  1096. -G
  1097.  
  1098. These options control the details of GNU C++ compilation itself.
  1099.  
  1100. -ansi
  1101. With this option enabled, differences between GNU C++ and AT&T C++ are also flagged.  Because the C++ language definition 
  1102. and the ANSI draft differ on the interpretation of syntactically identical constructs, it is unlikely that this flag could possibly be of any 
  1103. real use.  (For this reason, this flag is currently not fully implemented).
  1104.  
  1105. -traditional
  1106. The other aspects of "-traditional" are equivalent to GCC.
  1107.  
  1108. The predefined macro "__cplusplus" is defined to identify compilation for C++ 2.0.  C++ version 1.2 uses "c_plusplus" as its 
  1109. identifying macro.  Since GNU C++ implements version 2.0 semantics, the former is defined, while the latter is not.  The macro 
  1110. "__GNUG__" is also defined, so that features specific to GNU C++ can be used conditionally.
  1111.  
  1112. -O
  1113. -g
  1114. -w
  1115. -W
  1116. -Wimplicit
  1117. -Wreturn-type
  1118. -Wunused
  1119. -Wswitch
  1120. -Wcomment
  1121. -Wtrigraphs
  1122. -Wall
  1123. -Wshadow
  1124. -Wid-clash-{len}
  1125. -Wpointer-arith
  1126. -Wcast-qual
  1127. -Wwrite-strings
  1128. -p
  1129. -pg
  1130. -l{library}
  1131. -L{dir}
  1132. -nostdlib
  1133. -m{machinespec}
  1134. -m68020
  1135. -mc68020
  1136. -m68000
  1137. -mc68000
  1138. -m68881
  1139. -msoft-float
  1140. -mshort
  1141. -mint
  1142. -mnobitfield
  1143. -mbitfield
  1144. -mrtd
  1145. -f{flag}
  1146. m -ffloat-store
  1147. -fno-asm
  1148. -fno-defer-pop
  1149. -fstrength-reduce
  1150. -fcombine-regs
  1151. -fforce-mem
  1152. -fforce-addr
  1153. -fomit-frame-pointer
  1154. -finline-functions
  1155.  
  1156. -fdefault-inline
  1157. If this option is enabled then member functions defined inside class scope are compiled inline by default, i.e., you don't need to add 
  1158. "inline" in front of the member function name.  By popular demand, this option is now the default.  To keep GNU C++ from inlining 
  1159. these member functions, specify "-fno-default-inline".
  1160.  
  1161. -fcaller-saves
  1162. -fkeep-inline-functions
  1163. -fwritable-strings
  1164. -fcond-mismatch
  1165. -fno-function-cse
  1166. -fvolatile
  1167. -fshared-data
  1168. -funsigned-char
  1169. -fsigned-char
  1170. -ffixed-{reg}
  1171. -fcall-used-{reg}
  1172. -fcall-saved-{reg}
  1173.  
  1174. -fstrict-prototype
  1175. Consider the declaration "int foo ();".  In C++, this means that the function "foo" takes no arguments.  In ANSI C, this is declared "int 
  1176. foo(void);".  With the flag "-fno-strict-prototype", declaring functions with no arguments is equivalent to declaring its argument list to 
  1177. be untyped, i.e., "int foo ();" is equivalent to
  1178. saying "int foo (...);".
  1179.  
  1180. -felide-constructors
  1181. Using this option instructs the compiler to be smarter about when it can elide constructors.  With out this flag, GNU C++ and cfront 
  1182. both generate effectively the same code for example:
  1183.  
  1184. A foo ();
  1185. A x (foo ());   // x is initialized by `foo ()', no ctor called here
  1186. A y = foo ();   // call to `foo ()' heads to temporary,
  1187.                 // y is initialized from the temporary.
  1188.  
  1189. Note the difference!  With this flag, GNU C++ initializes `y' directly from the call to `foo ()' without going through a temporary.
  1190.  
  1191. -fall-virtual
  1192. When the "-fall-virtual" option is used, all member functions (except for constructor functions and new/delete member operators) 
  1193. declared in the same class with a "method-call" operator method have
  1194. entries made for them in the vtable for the given class.  In effect, all of these methods become "implicitly virtual."
  1195.  
  1196. This does not mean that all calls to these methods will be made through the vtable.  There are some circumstances under which it is 
  1197. obvious that a call to a given virtual function can be made directly, and in these cases the calls still go direct.
  1198.  
  1199. The effect of making all methods of a class with a declared `operator->()()' implicitly virtual using "-fall-virtual" extends also to all 
  1200. non-constructor methods of any class derived from such a class.
  1201.  
  1202. -fthis-is-variable
  1203. The incorporation of user-defined free store management into C++ has made assignment to "this" an anachronism.  Therefore, by 
  1204. default GNU C++ treats the type of "this" in a member function of "class X" "X *const".  In other words, it is illegal to assign to "this" 
  1205. within a class member function.  However, for backwards compatibility, you can invoke the old behavior by using "-fthis-is-variable".
  1206.  
  1207. -fsave-memoized
  1208. -fmemoize-lookups
  1209. These flags are of use to get the compiler to compile programs faster using heuristics.  They are not on by default since they only 
  1210. do so about half the time.  They other half of the time programs compile more slowly (and take more memory).
  1211.  
  1212. The first time the compiler must build a call to a member function (or reference to a data member), it must (1) determine whether the 
  1213. class implements member functions of that name (2) resolve which member function to call (which involves figuring out what sorts 
  1214. of type conversions need to be made), and (3) check the visibility of the member function to the caller.  All of this adds up to slower 
  1215. compilation. Normally, the second time a call is made to that member function (or reference to that data member), it must go 
  1216. through the same lengthy process again.  This means that code like this
  1217.  
  1218.   cout << "This " << p << " has " << n << " legs.\n";
  1219.  
  1220. makes six passes through all three steps.  By using a software cache, a "hit" significantly reduces this cost.  Unfortunately, using the 
  1221. cache introduces another layer of mechanisms which must be implemented, and so incurrs its own overhead.  The 
  1222. "-fmemoize-lookups" enables the software cache.
  1223.  
  1224. Because access privileges (visibility) to members and member functions may differ from one function context to the next, may need 
  1225. to be flushed.  With the "-fmemoize-lookups" flag, the cache is flushed after every function that is compiled.  With the 
  1226. "-fsave-memoized"  flag, when the compiler determines that the context of the last function compiled would yield the same access 
  1227. privileges of the next function to compile, it preserves the cache.  This really helps when defining many member functions for the 
  1228. same class: with the exception of member functions which are friends of other classes, each member function has exactly the same 
  1229. access privileges as every other, and the cache need not be flushed.
  1230.  
  1231. -pedantic
  1232. Attempt to support strict ANSI standard C.  Since C++ invalidates a number of ANSI constructions, this switch is of dubious value.  
  1233. Some attempt has been made to warn about non-standard C++ features, however, even this is of uncertain value, as there are two 
  1234. C++ standards currently in existence: the standard as documented by AT&T, and the standard as implemented by the AT&T C++ 
  1235. compiler.  Valid C++ programs should compile properly with or without this switch.  However, without this switch, certain useful or 
  1236. traditional constructs banned by the standard are supported.  With this switch, they are rejected.  There is no reason to use this 
  1237. switch; it exists only to satisfy curious pedants.
  1238.  
  1239. The options, which control the behaviour of the C preprocessor are the same as for GCC (See The C-Compiler Driver, last section).
  1240.  
  1241.  
  1242. The Preprocessor
  1243.  
  1244. Most often when you use the C preprocessor you will not have to invoke it explicitly: the C compiler will do so automatically. 
  1245. However, the preprocessor is sometimes useful individually.
  1246.  
  1247.  
  1248. Invoking the C Preprocessor
  1249.  
  1250. The C preprocessor expects two file names as arguments, "infile" and "outfile". The preprocessor reads "infile" together with any 
  1251. other files it specifies with "#include".  All the output generated by the combined input files is written in "outfile".
  1252.  
  1253. Either "infile" or "outfile" may be "-", which as "infile" means to read from standard input and as "outfile" means to write to standard 
  1254. output.  Also, if "outfile" or both file names are omitted, the standard output and standard input are used for the omitted file names.
  1255.  
  1256. Here is a table of command options accepted by the C preprocessor.  Most of them can also be given when compiling a C 
  1257. program; they are passed along automatically to the preprocessor when it is invoked by the compiler.
  1258.  
  1259. -P
  1260. Inhibit generation of "#"-lines with line-number information in the output from the preprocessor. This might be useful when running 
  1261. the preprocessor on something that is not C code and will be sent to a program which might be confused by the "#"-lines
  1262.  
  1263. -C
  1264. Do not discard comments: pass them through to the output file. Comments appearing in arguments of a macro call will be copied to 
  1265. the output before the expansion of the macro call.
  1266.  
  1267. -T
  1268. Process ANSI standard trigraph sequences.  These are three-character sequences, all starting with "??", that are defined by ANSI C 
  1269. to stand for single characters.  For example, "??/" stands for "\", so "'??/n'" is a character constant for Newline. Strictly speaking, the 
  1270. GNU C preprocessor does not support all programs in ANSI Standard C unless "-T" is used, but if you ever notice the difference it 
  1271. will be with relief.
  1272.  
  1273. You don't want to know any more about trigraphs.
  1274.  
  1275. -pedantic
  1276. Issue warnings required by the ANSI C standard in certain cases such as when text other than a comment follows "#else" or 
  1277. "#endif".
  1278.  
  1279.  
  1280. -I {directory}
  1281. Add the directory {directory} to the end of the list of directories to be searched for header files.  This can be used to override a 
  1282. system header file, substituting your own version, since these directories are searched before the system header file directories.  If 
  1283. you use more than one "-I" option, the directories are scanned in left-to-right order; the standard system directories come after.
  1284.  
  1285.  -I-
  1286. Any directories specified with "-I" options before the "-I-" option are searched only for the case of "#include "{file}""; they are not 
  1287. searched for "#include <{file}>".
  1288.  
  1289. If additional directories are specified with "-I" options after the "-I-", these directories are searched for all "#include" directives.
  1290.  
  1291. In addition, the "-I-" option inhibits the use of the current directory as the first search directory for "#include "{file}"".  Therefore, the 
  1292. current directory is searched only if it is requested explicitly with "-I.".  Specifying both "-I-" and "-I." allows you to control precisely 
  1293. which directories are searched before the current one and which are searched after.
  1294.  
  1295. -nostdinc
  1296. Do not search the standard system directories for header files.  Only the directories you have specified with "-I" options (and the 
  1297. current directory, if appropriate) are searched.
  1298.  
  1299. -D {name}
  1300. Predefine {name} as a macro, with definition "1".
  1301.  
  1302. -D {name}={definition}
  1303. Predefine {name} as a macro, with definition{definition}.  There are no restrictions on the contents of {definition}, but if you are 
  1304. invoking the preprocessor from a shell or shell-like program you may need to use the shell's quoting syntax to protect characters 
  1305. such as spaces that have a meaning in the shell syntax.
  1306.  
  1307. -U {name}
  1308. Do not predefine {name}. If both "-U" and "-D" are specified for one name, the "-U" beats the "-D" and the name is not predefined.
  1309.  
  1310. -undef
  1311. Do not predefine any nonstandard macros.
  1312.  
  1313. -d
  1314. Instead of outputting the result of preprocessing, output a list of "#define" commands for all the macros defined during the 
  1315. execution of the preprocessor.
  1316.  
  1317. -M
  1318. Instead of outputting the result of preprocessing, output a rule suitable for "make" describing the dependencies of the main source 
  1319. file.  The preprocessor outputs one "make" rule containing the object file name for that source file, a colon, and the names of all the 
  1320. included files.  If there are many included files then the rule is split into several lines using "\"-newline.
  1321.  
  1322. This feature is used in automatic updating of makefiles.
  1323.  
  1324. -MM
  1325. Like "-M" but mention only the files included with "#include "{file}"".  System header files included with "#include <{file}>" are 
  1326. omitted.
  1327.  
  1328. -i {file}
  1329. Process {file} as input, discarding the resulting output, before processing the regular input file.  Because the output generated from 
  1330. {file} is discarded, the only effect of "-i {file}" is to make the macros defined in {file} available for use in the main input.
  1331.  
  1332.  
  1333. Predefined Macros
  1334.  
  1335. The standard predefined macros are available with the same meanings regardless of the machine or operating system on which 
  1336. you are using GNU C.  Their names all start and end with double underscores.  Those preceding "__GNUC__" in this table are 
  1337. standardized by ANSI C; the rest are GNU C extensions.
  1338.  
  1339. __FILE__
  1340. This macro expands to the name of the current input file, in the form of a C string constant.
  1341.  
  1342. __LINE__
  1343. This macro expands to the current input line number, in the form of a decimal integer constant.  While we call it a predefined macro, 
  1344. it's a pretty strange macro, since its "definition" changes with each new line of source code.
  1345.  
  1346. This and "__FILE__" are useful in generating an error message to report an inconsistency detected by the program; the message 
  1347. can state the source line at which the inconsistency was detected. For example,
  1348.  
  1349. fprintf (stderr, 
  1350.      "Internal error: negative string length "
  1351.          "%d at %s, line %d.",
  1352.          length, __FILE__, __LINE__);
  1353.  
  1354. A "#include" command changes the expansions of "__FILE__" and "__LINE__" to correspond to the included file.  At the end of that 
  1355. file, when processing resumes on the input file that contained the "#include" command, the expansions of "__FILE__" and 
  1356. "__LINE__" revert to the values they had before the "#include" (but "__LINE__" is then incremented by one as processing moves to 
  1357. the line after the "#include").
  1358.  
  1359. The expansions of both "__FILE__" and "__LINE__" are altered if a "#line" command is used.
  1360.  
  1361. __DATE__
  1362. This macro expands to a string constant that describes the date on which the preprocessor is being run.  The string constant 
  1363. contains eleven characters and looks like "Jan 29 1987" or "Apr 1 1905".
  1364.  
  1365. __TIME__
  1366. This macro expands to a string constant that describes the time at which the preprocessor is being run.  The string constant 
  1367. contains eight characters and looks like "23:59:01".
  1368.  
  1369. __STDC__
  1370. This macro expands to the constant 1, to signify that this is ANSI Standard C. (Whether that is actually true depends on what C 
  1371. compiler will operate on the output from the preprocessor.)
  1372.  
  1373. __GNUC__
  1374. This macro is defined if and only if this is GNU C.  This macro is defined only when the entire GNU C compiler is in use; if you 
  1375. invoke the preprocessor directly, "__GNUC__" is undefined.
  1376.  
  1377. __STRICT_ANSI__
  1378. This macro is defined if and only if the "-ansi" switch was specified when GNU C was invoked.  Its definition is the null string. This 
  1379. macro exists primarily to direct certain GNU header files not to define certain traditional U**x constructs which are incompatible with 
  1380. ANSI C.
  1381.  
  1382. __VERSION__
  1383. This macro expands to a string which describes the version number of GNU C.  The string is normally a sequence of decimal 
  1384. numbers separated by periods, such as "1.18".  The only reasonable use of this macro is to incorporate it into a string constant.
  1385.  
  1386.  __OPTIMIZE__
  1387. This macro is defined in optimizing compilations.  It causes certain GNU header files to define alternative macro definitions for some 
  1388. system library functions.  It is unwise to refer to or test the definition of this macro unless you make very sure that programs will 
  1389. execute with the same effect regardless.
  1390.  
  1391. __CHAR_UNSIGNED__
  1392. This macro is defined if and only if the data type "char" is unsigned on the target machine. It exists to cause the standard header file 
  1393. "limit.h" to work correctly.  It is bad practice to refer to this macro yourself; instead, refer to the standard macros defined in "limit.h".
  1394.  
  1395. __MSHORT__
  1396. This macro is defined, if "gcc.ttp" is invoked with the "-mshort" option, which causes integers to be 16 bit. Please carefully examine 
  1397. the prototypes in the "#include <>" headers for types before using "-mshort".
  1398.  
  1399. __MINT__
  1400. This macros is defined, if "gcc.ttp" is invoked with the "-mint" option. This macros activates some portions of the header files, which 
  1401. are MiNT specific. Up to version 8 of the MiNT libraries and headers the header files of J.R.Bammi's libraries are compatible with the 
  1402. ones from Eric Smith's library. Therefore if you were writing programs for MiNT you could stick to Bammi's headers and use the 
  1403. "-mint" option. I don't know, if header files are still compatible with version 10 of the MiNT libraries.
  1404.  
  1405.  
  1406. Apart from the above listed macros, there are usually some more to indicate what type of system and machine is in use. For 
  1407. example "unix" is normally defined on all U**x systems. Other macros describe more or less the type of CPU the system runs on. 
  1408. GNU CC for the Atari ST has the following macros predefined.
  1409.  
  1410. atarist
  1411. gem
  1412. m68k
  1413.  
  1414. Please keep in mind, that these macros are only defined, if the preprocessor is invoked from the compiler driver "gcc.ttp".
  1415.  
  1416. These predefined symbols are not only nonstandard, they are contrary to the ANSI standard because their names do not start with 
  1417. underscores.  However, the GNU C preprocessor would be useless if it did not predefine the same names that are normally 
  1418. predefined on the system and machine you are using.  Even system header files check the predefined names and will generate 
  1419. incorrect declarations if they do not find the names that are expected.
  1420.  
  1421. The "-ansi" option which requests complete support for ANSI C inhibits the definition of these predefined symbols.
  1422.  
  1423.  
  1424. Generating Dependency Information
  1425.  
  1426.   The preprocessor has a not so well known feature, which lets you generate dependency information for makefiles and write these 
  1427. dependencies directly into a file. 
  1428.  
  1429.   You already know about the options "-M" and "-MM" for the compiler driver and the preprocessor (See The Preprocessor for more 
  1430. info). 
  1431.  
  1432. DEPENDENCIES_OUTPUT
  1433. SUNPRO_DEPENDENCIES
  1434.  
  1435.  
  1436. The GNU Assembler (GAS)
  1437.  
  1438.   Most of the time you will be programming in C. But there may certain situations, where it is feasible to write in assembler. Time is 
  1439. usually a main reason to dive into assembler programming, when you have to squeeze the last redundant machine cycle out of 
  1440. your routine, to meet certain time limits. Another reason might be, that you have to do very low level stuff like fiddling with bits in the 
  1441. registers of a peripheral chip. An example for low level stuff is the startup module "crt0.o", which is written in assembler.
  1442.  
  1443.   If you already have some experience in assembler programming, you might miss the feature of creating macros. This is not really a 
  1444. lack given the fact, that the assembler originated from an U**x environment.  Under this operating system there is a tools for nearly 
  1445. every purpose.  If you were in the need of an extensive macros facility, you would use the M4 macro processor. A GNU version of 
  1446. the M4 macro processor exists. It should be no problem to port it to the Atari with GCC. For some macro processing tasks you just 
  1447. as well use the C preprocessor. What I personally miss is the ability to produce a listing, but this will be fixed with GAS 1.92.
  1448.  
  1449.   One command line option was introduced only very lately. The changes for the option "-m68040" were part of update 20, which 
  1450. Bammi released around end of April 1992. The assembler identifies itself, when invoked with the "-v" option with the string "GNU 
  1451. assembler version 1.38 atariST PatchLevel 2".
  1452.  
  1453.  
  1454. Invoking the Assembler
  1455.  
  1456. "gcc-as.ttp" supports the following command line options. The output is written to "a.out" by default.
  1457.  
  1458. -G
  1459. assembles the debugging information the C compiler included into the output. Without this flag the debugging information is 
  1460. otherwise discarded.
  1461.  
  1462. -L
  1463. Normally all labels, that start with a "L" are discarded and don't show up as symbols in the object code module. They are local to 
  1464. that assembler module. If the "-L" option is given, all local labels will be included in the object code module.
  1465.  
  1466. -l
  1467. keep externals to 2 bit offset.
  1468.  
  1469. -m68000
  1470. -m68010
  1471. -m68020
  1472. -m68040
  1473. These options modify the behavior of assembler in respect of the used CPU. The M68020, for example, allows relative branches 
  1474. with 32-bit offset.
  1475.  
  1476. -o{filename}
  1477. writes the output to {filename} instead of{a.out}.
  1478.  
  1479. -R
  1480. The information, which normally would be assembled into the data section of the program, is moved into the text section.
  1481.  
  1482. -v
  1483. displays the version of the assembler.
  1484.  
  1485. -W
  1486. suppresses all warning messages.
  1487.  
  1488.  
  1489. Syntax
  1490.  
  1491. The assembler uses a slightly modified syntax from the one you might  know from other 68000 assemblers, which use the original 
  1492. Motorola syntax. The next sections trys to describe the syntax, GAS uses.
  1493.  
  1494. The most obvious differences are the missing "." and the usage of the at sign ("@"). The original Motorola syntax uses the "." to 
  1495. separate the size modifier ("b", "w", "l") from the main instruction. In Motorola syntax one would write "move.l #1,d0" to move a long 
  1496. word with value 1 into register "d0". With GAS you simple write "movel #1,d0". The "@" is used to mark an indirection equivalent to 
  1497. the Motorola parentheses. To move a long word of value 1 to the location addressed by "a0", you have to write "movel #1,a0@". 
  1498. The equivalent instruction expressed in Motorola "move.l #1,(a0)". The "#" indicates immediate data in both cases.
  1499.  
  1500.  
  1501. Register Names and Addressing Modes
  1502.  
  1503. The register mnemonics are "d0..d7" for the data registers and "a0..a7" or "sp" for address register and the stack pointer.  "pc" is the 
  1504. program counter, "sr" the status register, "ccr" the condition code register and "usp" the user stack  pointer.
  1505.  
  1506. The following table shows the operands GAS can parse. (The first part part describe the used abbreviations. The second part show 
  1507. the addressing modes with a equivalent C expression.)
  1508.  
  1509. numb:
  1510. a 8 bit number
  1511.  
  1512. numw:
  1513. a 16 bit number
  1514.  
  1515. numl:
  1516. a 32 bit number
  1517.  
  1518. dreg:
  1519. data register 0..7
  1520.  
  1521. reg:
  1522. address or data register
  1523.  
  1524. areg:
  1525. address register 0..7
  1526.  
  1527. apc:
  1528. address register or PC
  1529.  
  1530. num:
  1531. a 16 or 32 bit number
  1532.  
  1533. num2:
  1534. a 16 or 32 bit number
  1535.  
  1536. sz:
  1537. "w" or "l"; if omitted, "l" is  assumed.
  1538.  
  1539. scale:
  1540. 1 2 4 or 8. If omitted, 1 is assumed.
  1541.  
  1542.  
  1543. Addressing Modes
  1544. Immediate Data
  1545. #num                          --> NUM
  1546.  
  1547. Data- or Address Register Direct
  1548. dreg                          --> dreg
  1549. areg                          --> areg
  1550.  
  1551. Address Register Indirect
  1552. areg@                        --> *(areg)
  1553.  
  1554. Address Register Indirect with Postincrement or Predecrement
  1555. areg@+                        --> *(areg++)
  1556. areg@-                        --> *(--areg)
  1557.  
  1558. Address Register (or PC) Indirect with Displacement
  1559. apc@(numw)                    --> *(apc+numw) 
  1560.  
  1561. Address Register (or PC) Indirect with Index (8-Bit Displacement) (M68020 only)
  1562. apc@(num,reg:sz:scale)        --> *(apc+num+reg*scale)
  1563. apc@(reg:sz:scale)            --> same, with num=0
  1564.  
  1565. Memory Indirect Postindexed (M68020 only)
  1566. apc@(num)@(num2,reg:sz:scale) --> *(*(apc+num)+num2+reg*scale)
  1567. apc@(num)@(reg:sz:scale)      --> same, with num2=0
  1568. apc@(num)@(num2)              --> *(*(apc+num)+num2)
  1569.                                  (previous mode without an index reg)
  1570.  
  1571. Memory Indirect Preindexed (M68020 only)
  1572. apc@(num,reg:sz:scale)@(num2) --> *(*(apc+num+reg*scale)+num2)
  1573. apc@(reg:sz:scale)@(num2)     --> same, with num=0
  1574.  
  1575. Absolute Address
  1576. num:sz                        --> *(num)
  1577. num                           --> *(num) (sz L assumed)
  1578.  
  1579.  
  1580. Labels and Identifiers
  1581.  
  1582. User defined identifiers are basically defined by the same rules as C identifier. They may contain the digits 0..9, the letters A..z and 
  1583. the underscore and must not start with a digit. Identifier, which end with a ":" are labels. A special form of labels starts with a "L" or 
  1584. consists of only a digit. Both types are local labels, which disappear, when the assembly is complete (unless the "-L" option was 
  1585. specified). They can't be used to resolve external references.  The "L" type label are referenced by their name, just as any other
  1586. label. The digit type labels form a special kind of local labels. You might also call them temporary labels. They are especially useful 
  1587. when you have to create small loops, which poll a peripheral or fill a memory area. They are referenced by appending either a "f", for 
  1588. a forward reference, or a "b", for a backward reference, to the digit. Lets look at the following example, which is used to split a 
  1589. memory area starting at "0x80000". All data on an even addresses is copied to the area starting at "0x70000"; all data from odd 
  1590. addresses goes to the area starting at "0x78000".
  1591.  
  1592. start:
  1593.         lea     0x80000,a0
  1594.         lea     0x70000,a1
  1595.         lea     0x78000,a2
  1596.         movel   #0x7fff,d5
  1597. 0:                              | label "0" is defined
  1598.         moveb   a0@+,a1@+
  1599.         moveb   a0@+,a2@+
  1600.         dbra    d5,0b           | reference of label "0"
  1601.          ......
  1602.  
  1603. The label "0" is referenced 3 lines later by "0b", since the reference is backward. You can use the label "0" again at a later time to 
  1604. construct more such loops. Since this temporary labels are restricted to one digit in length, you can only build constructs, which 
  1605. use 10 temporary labels at the same time.
  1606.  
  1607.  
  1608. Comments
  1609.  
  1610. The above example also shows, that comments start with a "|".  "#" is also used to mark a comments. The C compiler and the 
  1611. preprocessor generate lines, that start with a "#".
  1612.  
  1613.  
  1614. Numerical and String Constants
  1615.  
  1616. Numerical values are given the same way as in a C programs. By default number are taken to be decimal. A leading "0" denotes an 
  1617. octal and a "0x" a hexadecimal value. Floating point numbers start with a "0f". The optional exponent starts with a "e" or "E". 
  1618.  
  1619. String constants are equivalent to C defined. They are enclosed in " " ". Some special character constants are defined by "\" and a 
  1620. following letter. These characters are possible:
  1621.  
  1622. \b
  1623. Backspace, Code 0x08
  1624.  
  1625. \t
  1626. Tab, Code 0x09
  1627.  
  1628. \n
  1629. Line Feed, Code 0x0a
  1630.  
  1631. \f
  1632. Form Feed, Code 0x0c
  1633.  
  1634. \r
  1635. Carriage Return, Code 0x0d
  1636.  
  1637. \\
  1638. Backslash itself
  1639.  
  1640. \"
  1641. Double Quote itself
  1642.  
  1643. \{number}
  1644. where {number} is a octal number with up to 3 digits specifying the character code.
  1645.  
  1646.  
  1647. Assignments and Operators
  1648.  
  1649. A "=" is used to assign a value to a Symbol.
  1650.  
  1651. Lexp_frame = 8
  1652.  
  1653. This is equivalent to the "equ" directive other assemblers use.
  1654.  
  1655. GAS supports addition (+), subtraction (-), multiplication(*), division (/), right shift (>), left shift (<), and (&), or (|), not (!), xor (^) 
  1656. and modulo (%) in expressions. The order of precedence is
  1657.  
  1658.           Rank    Examples
  1659. lowest   0       operand, (expression)
  1660.              1       + -
  1661.              2       & ^ ! |
  1662.              3       * / % < >
  1663.  
  1664. Parentheses are used to coerce the order of evaluation.
  1665.  
  1666.  
  1667. Segments, Location Counters and Labels
  1668.  
  1669. A program written in assembler language may be broken into three different segments; the TEXT, DATA and BSS sections. Pseudo 
  1670. opcodes are used to switch between the sections. The assembler maintains a location counter for each segment. When a label is 
  1671. used in the assembler input, it is assigned the current value of the active location counter. The location counter is incremented with 
  1672. every byte, that the assembler outputs. GAS actually allows you to have more than one TEXT or DATA segment. This is so to ease 
  1673. code generation by high level compilers.  The assembler concatenates the different sections in the end to form continuous regions 
  1674. of TEXT and/or DATA. When you do assembly programming by hand you would stick to the pseudo opcodes ".text" or ".data", 
  1675. which use text or data segment with number 0 by default.
  1676.  
  1677.  
  1678. Types
  1679.  
  1680. Symbol and Labels can be of one of three type. A Symbol is absolute; when it's values is known at assembly time. A assignment 
  1681. like "Lexp_frame = 8" gives the symbol "Lexp_frame" the absolute value 8. A symbol or label, which contains an offset from the 
  1682. beginning of a section, is called "relocatable". The actual value of this symbol can only be determined after the linking process or 
  1683. when the program is running in memory. The third type of symbols are undefined externals.  The actual value of this symbol is 
  1684. defined in an other program.
  1685.  
  1686. When different types of symbols are combined to form expressions the following rules apply: ("abs" = absolute, "rel" = relocatable, 
  1687. "ext" = undefined external)
  1688.  
  1689. abs + abs => abs
  1690. abs + rel = rel + abs => rel
  1691. abs + ext = ext + abs => ext
  1692.  
  1693. abs - abs => abs
  1694. rel - abs => rel
  1695. ext - abs => ext
  1696. rel - rel => abs
  1697. (makes only sense, when both relocatable expression are relative to same segment)
  1698.  
  1699. All other possible operators are only useful to form expressions with absolute values or symbols.
  1700.  
  1701.  
  1702. Supported Pseudo Opcodes (Directives)
  1703.  
  1704. All pseudo opcodes start with a ".". They are followed by 0, 1 or more expressions separated by commas (depending on the 
  1705. directive). The following table omits the pseudo opcodes, which include special information for debugging purposes (for GDB).
  1706.  
  1707. .abort
  1708. aborts the assembly on the point.
  1709.  
  1710. .align {integer}
  1711. aligns the current segment in size to {integer} power of 2. The maximum value of {integer} is 15. The lines
  1712.  
  1713. .text
  1714. some code ...
  1715. .align 10               | 2^10 = 1024
  1716. .data
  1717. some more code ...
  1718. .align 10               | 2^10 = 1024
  1719.  
  1720. will create text and data sections, which both have the size 1024, although the actual code, that goes into the sections may be 
  1721. smaller.
  1722.  
  1723. .ascii {string}[,{string},....]
  1724. includes the {string}('s) in the assembly output.
  1725.  
  1726. .asciz {string}[,{string},...]
  1727. This directive is the same as above, but additionally appends a "\0" character to the string.
  1728.  
  1729. .byte {expr}[,{expr},...]
  1730. puts consecutive bytes with value {expr} into the output.
  1731.  
  1732. .comm {identifier},{integer}
  1733. creates a common area of {integer} bytes in the current segment, which is referenced by {identifier}. The {identifier} is visible from 
  1734. the outside of the module. It can therefore be used to resolve external reference from other modules.
  1735.  
  1736. .data [{integer}]
  1737. switches to DATA section {integer}. If {integer} is omitted, data section 0 is selected.
  1738.  
  1739. .desc
  1740. Whatsit good for ???
  1741.  
  1742. .double {double}[,{double},...]
  1743. puts consecutive doubles with value {double} into the output.
  1744.  
  1745. .even
  1746. sets the location counter of the current segment to the next even value.
  1747.  
  1748. .file
  1749. .line
  1750. If a file is assembled, which was generated by a compiler or preprocessed by the C preprocessor, the input may contain lines like 
  1751. "# 132 stdio.h".  These lines are change by the assembler to the form
  1752.  
  1753. .line 132
  1754. .file stdio.h
  1755.  
  1756. .fill {count},{size},{expr}
  1757. puts {count} areas with {size} into the output. Each area contains the value {expr}.  {size} may be an even number up to or equal 
  1758. to 8. The line 
  1759.  
  1760. .fill 3, 4, 0xa5a
  1761.  
  1762. would put the following byte sequence in the output ("|" is only used to mark the size of the area.)
  1763.  
  1764. 00 00 0a 5a | 00 00 0a 5a | 00 00 0a 5a 
  1765.  
  1766. .float {float}[,{float},...]
  1767. puts consecutive floats with value {float} into the output.
  1768.  
  1769. .globl {identifier}[,{identifier},...]
  1770. When labels or identifiers are assigned, they are only locally defined.  The ".globl" directive gives {identifier} external scope. The 
  1771. label can therefore be used to resolve external references from other modules.  {identifier} don't have to be assigned in the current 
  1772. module, but can be defined in another module.
  1773.  
  1774. .int {expr}[,{expr},...]
  1775. puts consecutive integers (32 bit) with value {expr} into the output.
  1776.  
  1777. .lcomm {identifier},{integer}
  1778. is basically the same as ".comm", except that area is allocated in the BSS segment. The scope of {identifier} is only local (only  
  1779. visible in the module, where it is defined).
  1780.  
  1781. .long {expr}[,{expr},...]
  1782. same as "int".
  1783.  
  1784. .lsym {identifier},{expr}
  1785. sets the local {identifier} to the value of {expr}. The {identifier} is referenced by preceding it with a "L".  ("L{identifier}) (When I tried 
  1786. this, the linker threw a bomb. Trying again crashed the system.)
  1787.  
  1788. .octa
  1789. Whatsit good for ???
  1790.  
  1791. .org {expr}
  1792. sets the location counter of the current segment to {expr}.
  1793.  
  1794. .quad
  1795. Whatsit good for ???
  1796.  
  1797. .set {identifier},{expr}
  1798. sets {identifier} to the value of {expr}. If {identifier} is not explicitly marked external by the ".globl" directive, it has only local scope.
  1799.  
  1800. .short {expr}[,{expr},...]
  1801. puts consecutive shorts (16 bit) with value {expr} into the output.
  1802.  
  1803. .space {count}, {expr}
  1804. puts {count} consecutive number of bytes with value {expr} into the output. The line
  1805.  
  1806. .space 5,3
  1807.  
  1808. is equivalent to
  1809.  
  1810. .byte 3, 3, 3, 3, 3
  1811.  
  1812. The "space" directive is a special form of the "fill" directive.
  1813.  
  1814. .text [{integer}]
  1815. switches to TEXT section {integer}. If {integer} is omitted, text section 0 is selected.
  1816.   
  1817. .word {expr}[,{expr},...]
  1818. same as ".short".
  1819.  
  1820.  
  1821. The Utilities
  1822.  
  1823. This chapter describes the programs, which don't actually convert the source code into object code, but instead combine several 
  1824. object code modules to a runnable program or an object code library. Other programs can be used to print symbol information 
  1825. from either the object code or the executable. The last group of utility programs modify the executables in terms of memory usage 
  1826. and startup time.
  1827.  
  1828.  
  1829. The Linker ("gcc-ld.ttp")
  1830.  
  1831. A linker combines several object modules and extracts modules from a library to produce a runnable program. During this process 
  1832. all undefined symbol references are resolved. Additionally all sections from the object modules, which belong to either the TEXT, 
  1833. DATA or BSS are moved to the correct program segment. For example, all areas of all the object code modules, which have the 
  1834. type TEXT, are moved to form one large TEXT section. The same applies to the DATA and BSS sections.
  1835.  
  1836. For the most time you don't have invoke the linker explicitly. The compiler driver does the job for you. But in case you have to, the 
  1837. general syntax is:
  1838.  
  1839. gcc-ld [{options}] $GNULIB\crt0.o {file}.o -l{library}
  1840.  
  1841. The above syntax assumes, that the executable is produced from C source code, which normally makes is necessary to link a 
  1842. startup module and a library. If an executable from a self contained assembler text is to be created, the startup module "crt0.o" and 
  1843. the library might be missing.  "gcc-ld.ttp" creates a file "a.out" by default. The linker can also append a DRI compatible or an 
  1844. extended symbol table to the executable.
  1845.  
  1846. "gcc-ld.ttp" supports the following command line options.
  1847.  
  1848. -f{load flags}
  1849. Set the program load flags to {load flags}. The default program load flags is 7 (TT ram, fastload).
  1850.  
  1851. -h{altheap size}
  1852. Set the minalt size in the executable header to {altheap size}.  The default value is zero. Remember that value is specified in 128k 
  1853. units. What this means is (quoting mintsrc/mem.c): If (flags & F_ALTLOAD == 1), then we might decide to load in alternate RAM if 
  1854. enough is available. "enough" is: if more alt ram than ST ram, load there; otherwise, if more than (minalt+1)*128K alt ram available 
  1855. for heap space, load in alt ram ("minalt" is the high byte of flags).
  1856.  
  1857.  
  1858. -l{library}
  1859. Search {library} to satisfy unresolved references. The environment variable "GNULIB" is used to locate the library.  "GNULIB" 
  1860. contains a "," or ";" separated list of paths, each path without a trailing slash or backslash.
  1861.  
  1862. -L{directory}
  1863. Includes {directory} in the search path to locate a library.
  1864.  
  1865. -M
  1866. During the linking process extensive information about the encountered symbols is displayed.
  1867.  
  1868. -G
  1869. Instead of the standard DRI compatible symbol table, an extended symbol table is written, which allows symbol names to be up to 
  1870. 22 characters long. Most of the other utility programs have been updated to work with this format. The most benefit you get with 
  1871. "gprof.ttp" and "szadb" (the adb-like debugger, originally written for the Sozobon C compiler by Johann Rueg and Don Dugger and 
  1872. later significantly improved by Michal Jaegermann).
  1873.  
  1874. -o{filename}
  1875. The resulting output of the linking process is written to {filename} instead to "a.out".
  1876.  
  1877. -s
  1878. prevents the linker from attaching a symbol table to the executable.
  1879.  
  1880. -t
  1881. During the linking process the files loaded and the modules extracted from a library are displayed.
  1882.  
  1883. -x
  1884. This option discards all local symbols from the DRI symbol table. All global symbols are left in place.
  1885.  
  1886.  
  1887. sym-ld.ttp
  1888.  
  1889. "sym-ld.ttp" is a special version of the linker. His sole purpose is to create a special symbol file used by the GNU debugger. The 
  1890. following example show the usage. ("$" is the prompt of a CLI, "*" is the GDB prompt, "#" marks a comment)
  1891.  
  1892. $ gcc -c -g foo.c      # compile "foo.c"
  1893. $ gcc -o foo.prg foo.o -lgnu # link with normal "gcc-ld.ttp"
  1894. $ sym-ld -o foo.sym $(GNULIB)\crt0.o foo.o -lgnu
  1895.                        # (or -lgnu16 if you use -mshort)
  1896.                        # link with "sym-ld.ttp" to get symbol file
  1897. $ gdb
  1898. * exec-file foo.prg    # executable ("gcc-ld.ttp" linked Atari executable)
  1899. * symbol-file foo.sym  # symbols file ("sym-ld.ttp -o" linked)
  1900. * run
  1901. * <start doing gdb commands here>
  1902.  ...
  1903. * q
  1904. $                      # back
  1905.  
  1906.   Note the line in the example, where "sym-ld.ttp" is invoked. A library "gnugdb.olb" is used to create the symbol file. This is just like 
  1907. the normal library "gnu.olb" except, that is was compiled with the "-g" option. If you don't have this library, use the normal library 
  1908. ("-lgnu"). In this case you can't single step through library functions at the source level. Also note, that "sym-ld.ttp" is invoked without 
  1909. the "-r" option. This option was only necessary for some very early versions of "gdb".
  1910.  
  1911.   For a bit more detailed info about debugging with "gdb" turn to chapter Debugging.
  1912.  
  1913.  
  1914. The Archiver "gcc-ar.ttp"
  1915.  
  1916. The archivers main purpose is to make things in programming life easier. The archiver combines several object modules into one 
  1917. large library. At a later time the linker will then retrieve the modules needed to resolve all references. Without the library you would 
  1918. have to supply all modules by hand on the command line or the linker would have to search through all the files to resolve the 
  1919. references (The library "gnu.olb" contains around 150 modules).
  1920.  
  1921. The general syntax for invoking "gcc-ar.ttp" is:
  1922.  
  1923. gcc-ar {option} [{position}] {library} [{module}]
  1924.  
  1925. The {option} specifies the action to be taken on the {library} or a {module} of that {library}.  {option} also includes modifiers for 
  1926. the action. The optional {position} argument is a member of the {library}. It is used, to mark a specific position in the {library}; an 
  1927. "add" operation would than place a new module before or after that {position}. The next argument specifies the library. The 
  1928. recommended naming convention for the creation of a new libraries is {library}.olb. If you don't use this convention, the compiler 
  1929. driver "gcc.ttp" will have trouble finding them.  {module} is usually an object code file generated by the compiler.
  1930.  
  1931. "gcc-ar.ttp" supports the following command line options. If you don't use a {position} the named module is appended or moved to 
  1932. the end of the library
  1933.  
  1934. a
  1935. The "add", "replace" or "move" operation should place the "module" after "position".
  1936.  
  1937. b
  1938. The "add", "replace" or "move" operation should place the "module" before "position".
  1939.  
  1940. c
  1941. If the specified "library" does not exist, it is silently created. Without this option "gcc-ar.ttp" would give you a notice, that it created a 
  1942. new library.
  1943.  
  1944. d
  1945. deletes "module" from the "library".
  1946.  
  1947. i
  1948. This is the same as option "b".
  1949.  
  1950. l
  1951. This option is ignored. (Why is there in the first place ??)
  1952.  
  1953. m
  1954. Move a member around inside the library.
  1955.  
  1956. o
  1957. preserves the modification time of a module, that is extracted from the library.
  1958.  
  1959. p
  1960. This option pipes the specified "module" directly to "<stdout>".
  1961.  
  1962. q
  1963. A quick append is performed.
  1964.  
  1965. r
  1966. causes "module" to be replaced. If the named module is not already present, it is appended. This is also the default action, when no 
  1967. "option" is given.
  1968.  
  1969. s
  1970. creates special member in the library called "__.SYMDEF", which contains a directory of the external names defined by all the other 
  1971. members.
  1972.  
  1973. t
  1974. lists the members, that are currently in the "library". If the option "v" is also given, additional information about file permissions, user- 
  1975. and group-id's and last modification date of the members are displayed. Of course, file permissions and user- and group-id's don't 
  1976. make much sense on the Atari ST.
  1977.  
  1978. u
  1979. If this option is given, an existing module in the library is only replaced, if the modification time of the new module is newer than the 
  1980. modification time of the one already in the library.
  1981.  
  1982. v
  1983. gives you some additional information depending on the operation, that currently performed.
  1984.  
  1985. x
  1986. Extract "module" from the "library".
  1987.  
  1988.  
  1989. Listing Symbols
  1990.  
  1991. There are two programs available for printing symbols; each for symbols of a different kind.  "gcc-nm.ttp" list symbols in GNU object 
  1992. files and object libraries.  "cnm.ttp" lists symbols from a DRI compatible or extended symbol table attached to an executable.
  1993.  
  1994. gcc-nm.ttp
  1995. The output of  "gcc-nm.ttp" looks like the following sample:
  1996.  
  1997. 00000870 b _Lbss
  1998.          U _alloca
  1999. 000003b4 t _glob_dir_to_array
  2000. 00000532 T _glob_filename
  2001. 00000248 T _glob_vector
  2002.          U _malloc
  2003. 0000086c D _noglob_dot_filenames
  2004.          U _opendir
  2005.          U _readdir
  2006. 00000000 t gcc_compiled.
  2007.  
  2008. The first column displays the relative address of that symbol in the object file. If the symbol has the type "U" (undefined external) the 
  2009. space in left blank. The next column shows the type of the symbol. In general, symbols, which have an external scope (visible for 
  2010. other object module) are marked with an uppercase letter. Symbols, which are local to the object file are marked with lowercase 
  2011. letters. The following letters are possible:
  2012.  
  2013. C
  2014. marks variables, which are defined in that source module, but not initialized. A declaration like
  2015.  
  2016. int variable;
  2017.  
  2018. would create a line marked with a "C". The first column would  show the size of that variable in bytes instead of the relative address 
  2019. in the object module.
  2020.  
  2021. b
  2022. Variables, which are declared with
  2023.  
  2024. static int variable;
  2025.  
  2026. are displayed with a "b".
  2027.  
  2028. D
  2029. marks variables, which are initialized at declaration time. A declaration like
  2030.  
  2031. int variable = 1;
  2032.  
  2033. would show as a line with a "D" in it.
  2034.  
  2035. d
  2036. Variables, which are initialized at declaration time declared are displayed with a "d". A declaration like
  2037.  
  2038. static int variable = 1;
  2039.  
  2040. would create a line marked with a "d".
  2041.  
  2042. t,T
  2043. mark text (in other words: actual program code). Functions in your C source, which have the storage class "static", would be 
  2044. displayed with a "t". All other functions in that source module, which are visible to other modules, would show up with a "T".
  2045.  
  2046. U
  2047. All functions, which are defined in other modules and referenced in this module, are displayed with a "U".
  2048.  
  2049. The last column shows the symbol name.
  2050.  
  2051. "gcc-nm.ttp" supports the following command line options.
  2052.  
  2053. -a
  2054. In case a file is compiled with the "-g" or "-gg" option, special information for debugging purposes is included in the object code. 
  2055. This information is listed by supplying the "-a" option.
  2056.  
  2057. -g
  2058. This option restricts the output to include only symbols, which have an external scope.
  2059.  
  2060. -n
  2061. Without any options the output is sorted in ascii order. By supplying the "-n", the listing is sorted in numerical order by the 
  2062. addresses in first column.
  2063.  
  2064. -o
  2065. If this option is given, every output line is preceded by a filename in the form "file:", naming the file in which the symbol appears. If 
  2066. the file to be listed, is an archive, the line begins in the form "library(member):".
  2067.  
  2068. -p
  2069. The symbols are listed in the order as they appear in the object code module.
  2070.  
  2071. -r
  2072. The output is sorted in reverse ascii order.
  2073.  
  2074. -s
  2075. Archives may contain a special member called "__.SYMDEF". Don't ask me about it purpose. Anyway, using this option show the 
  2076. content of this member.
  2077.  
  2078. -u
  2079. Only undefined symbols are listed.
  2080.  
  2081. cnm.ttp
  2082.  
  2083. "cnm.ttp" prints the symbols which are attached to an executable.
  2084.  
  2085.  
  2086. Modifying the Executables
  2087.  
  2088. The programs, which are described in the following sections can be used to modify an already existing executable, but this only 
  2089. works under the assumption, that the symbol table is still attached to the executable. So, if you want to modify the memory usage of 
  2090. a program at a later time, you should keep the unstripped executables around or use the command "xstrip.ttp" and keep only the 
  2091. "_stksize" symbol.
  2092.  
  2093. fixstk.ttp
  2094. "fixstk.ttp" is used to modify the current stacksize of an executable.  It does this by looking up the symbol "_stksize" in the symbol 
  2095. table portion of the file and than changes the values of the location where "_stksize" points to. The usage is:
  2096.  
  2097. fixstk {size} [{filename}]
  2098.  
  2099. {size} is the stacksize in Bytes, KBytes or MBytes. To specify {size} in Kbytes or Mbytes, append a "K" or a "M" to the integer 
  2100. number.
  2101.  
  2102. For dumping applications like Scott Kolodzieski's port of GNU Emacs 18.57 "fixstk.ttp" looks up the symbol "_initial_stack" instead of 
  2103. "_stksize".
  2104.  
  2105. fixstk 128K gcc-as.ttp
  2106.  
  2107. sets the stacksize of "gcc-as.ttp" to 128 Kbytes.
  2108.  
  2109. toglclr.ttp
  2110. toglclr [-fload] [-frun] [-fram] {files} ...
  2111.  
  2112. -fload
  2113. Toggle the "fast load" flag.
  2114.  
  2115. -frun
  2116. Toggle the "fast run" flag.
  2117.  
  2118. -fram
  2119. Toggle the "fast ram malloc" flag.
  2120.  
  2121.   If TOS launches an application, it clears all memory starting from the BSS section to the end of the TPA. With earlier TOS versions 
  2122. (pre TOS 1.4) this could take quite a considerable amount of time. The clearing algorithm was improved during the different TOS 
  2123. releases, but it is still used, although most of the existing programs don't need a cleared memory. Well, most is not all; therefore for 
  2124. compatibility sake the feature will stay in place.
  2125.  
  2126.   With TOS 1.4 you can keep the GEMDOS loader from clearing all memory.  The long word with offset 0x16 in the program header 
  2127. is used to determine whether the memory should be cleared or not. Setting the bit 0 of this longword to 1 prevents the loader from 
  2128. clearing all memory.  "toglclr.ttp" serves exactly that purpose, namely toggling this long word.
  2129.  
  2130.   TOS 2.x and 3.x gave another two bits in the above mentioned longword a meaning. The "fast run" bit 1 is used to determine, if a 
  2131. program should be started in ordinary ST-ram (bit 1 = 0) or in alternate ram. In
  2132. case of the TT or the SST68030 from Dave Small, this is ram which is not slowed down by any video hardware.
  2133.  
  2134.   The "fast ram malloc" bit 2 determines, if any subsequent malloc's, which a program might do, should be satisfied from slow 
  2135. ST-ram (bit 2 = 0) or from alterate ram. All these flags have been introduced to increase compatibility between the different TOS 
  2136. versions.
  2137.  
  2138. xstrip.ttp
  2139.   "xstrip.ttp" removes the symbol table from a TOS executable file.  The default behaviour, which is to completely remove the symbol 
  2140. table, may be modified by specifying additional command line optione. The systax for the xstrip command is
  2141.  
  2142. xstrip [-a] [-g] [-k] [-l {names}] {files} ...
  2143.  
  2144. -a
  2145. Really remove all of the symbol table. Leave nothing.
  2146.  
  2147. -g
  2148. This option causes "xstrip.ttp" to keep all global symbols.
  2149.  
  2150. -k
  2151. keeps the "_stksize" symbol, so that the stack size can be adjusted even for a nearly-stripped GCC produced executables.
  2152.  
  2153. -l {names}
  2154. keeps all symbols listed in a file {names} (one symbol per line).
  2155.  
  2156. Both "-k" and "-l" options convert the extended symbols into regular ones (DRI compatible).
  2157.  
  2158.  
  2159. Getting Information about Executables
  2160.  
  2161. printstk.ttp
  2162. "printstk.ttp" works basically the same way as "fixstk.ttp", but displays the current value at the location "_stksize" or "_initial_stack". 
  2163. The usage is:
  2164.  
  2165. printstk [{filename}]
  2166.  
  2167. If {filename} is not specified it defaults to ".\gcc-cc1.ttp".  If "printstk.ttp" is used on some of the executables of the GCC distribution, 
  2168. you should see a value of "-1", which means that all available memory is used by the program (at least for the programs 
  2169. "gcc-cpp.ttp" and "gcc-cc1.ttp").
  2170.  
  2171. size68.ttp
  2172.   "size68.ttp" is used to print information, which is found in the the header of an executable program file. A sample output is shown in 
  2173. the following lines.
  2174.  
  2175. c:\ => size68 temacs 
  2176. temacs: 
  2177.         text size       245884 
  2178.         data size       160604 
  2179.         bss size        11552 
  2180.         symbol size     36274 
  2181.         File is relocatable 
  2182.  
  2183.         BSS and high mem cleared on startup 
  2184.  
  2185.   The value of "text size" is the actual size of the program code; the TEXT segment. The value of "data size" gives the size of 
  2186. initialized data; the DATA segment. For example, if you define a variable "char array[10] = "foobar";", the string "foobar" is moved to 
  2187. the data segment during the linking process. The value of "bss size" is the size of the BSS segment. If you define a global variable 
  2188. "char array[10];", this variable "array" would end up the BSS segment. The BSS segment is initialized to zero from the GEMDOS 
  2189. loader, when the program is loaded into memory. The memory usage during the programs runtime can't simply be calculated by 
  2190. adding the three values, since this doesn't take into account the memory, which might be dynamically allocated.
  2191.  
  2192.   The value of "symbol table" is the size of the symbol table, which is appended to the three segments. The symbol table is only 
  2193. used, when the program is invoked under the control of a debugger. The symbol table doesn't use up any memory, when the 
  2194. program is launched from the desktop or a CLI. The next line says, that the program file is relocatable. As far as I know is every 
  2195. program file relocatable on the
  2196. ST. The last line indicates, that the BSS section and the all available memory ("high mem") is cleared upon startup. On systems with 
  2197. lots of memory, this can take quite a bit of time. You can keep the GEMDOS loader from clearing all memory by toggling a bit in the 
  2198. header. See "toglclr.ttp" for more info.
  2199.  
  2200.  
  2201. Debugging Programs
  2202.  
  2203.   In general, you have two choices for debugging; machine and source level debugging. Most of the time you will prefer the source 
  2204. level debugging. 
  2205.  
  2206. This chapter is not ready yet. If you have some ideas, what should go into this section, please tell me.
  2207.